-
Notifications
You must be signed in to change notification settings - Fork 127
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}.
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.
TODO(srawlins): Document
TODO(srawlins): Document
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
TODO(srawlins): Document