-
Notifications
You must be signed in to change notification settings - Fork 118
Doc comment directives
Dartdoc supports several directives within Dart doc comments. Each directive is then processed during documentation generation, and new text is inserted in place of the directive. Not all directives are processed package documentation at https://pub.dev/.
Doc comment directives look something like {@DIRECTIVE ARG=VALUE ...}. Some require a closing directive, such as {@template} and {@endtemplate}.
You can document an element with a doc comment, and direct dartdoc to not include this documentation in the generated output, by including a line in the doc comment with the @nodoc directive.
Elements such as libraries and classes can be grouped into categories and sub-categories by adding {@category CATEGORY NAME} and {@subCategory SUB-CATEGORY NAME} in doc comments. Each category then gets its own documentation page, listing all of the categorized elements.
TODO(srawlins): Document
You can inline examples from the file system with the {@example} directive. You can specify the file path, the region, and the example language, with the following syntax:
{@example PATH [region=NAME] [lang=NAME]}
All example file names must have the extension, .md, and this extension must not be specified in the example PATH. PATH must be specified as a relative path from the root of the project root directory of the project for which docs are being generated. Given dir/file.dart as PATH, an example will be extracted from dir/file.dart.md, relative to the project root directory.
During doc generation, dartdoc will replace the {@example} directive with the contents of the example file, verbatim.
TODO(srawlins): Document region, lang, --example-path-prefix.
You can render plain, unmodified HTML by including it between an {@inject-html} directive and an {@end-inject-html} directive. The directives take no arguments:
{@inject-html}
INJECTED HTML
{@end-inject-html}
The {@inject-html} directive is only available when the --inject-html flag is passed to dartdoc. It is not available for documentation published on https://pub.dev.
You can embed HTML5 videos with the {@animation} directive. This directive accepts width and height arguments, and an optional ID argument:
{@animation 320 240 URL [id=ID]}
This directive renders the HTML which embeds an HTML5 video.
The optional ID should be a unique id that is a valid JavaScript identifier, and will be used as the id for the video tag. If no ID is supplied, then a unique identifier (starting with "animation_") will be generated.
The width and height must be integers specifying the dimensions of the video file in pixels.
You can embed YouTube videos with the {@youtube} directive. This directive accepts width and height arguments, using the following syntax:
{@youtube 320 240 https://www.youtube.com/watch?v=oHg5SJYRHA0}
This directive embeds the YouTube video with id "oHg5SJYRHA0" into the documentation page, with a width of 320 pixels, and a height of 240 pixels. The height and width are used to calculate the aspect ratio of the video; the video is always rendered to take up all available horizontal space to accommodate different screen sizes on desktop and mobile.
The video URL must have the following format: https://www.youtube.com/watch?v=oHg5SJYRHA0. This format can usually be found in the address bar of the browser when viewing a YouTube video.
TODO(srawlins): Document
Dartdoc uses some heuristics to decide what the public-facing libraries are, and which public-facing library is the "canonical" location for an element. When that heuristic needs to be overridden, a user can use this directive. Example:
{@canonicalFor some_library.SomeClass}