| commit | 91f4643b1b969e05668478ca2457289f971b28a3 | [log] [tgz] |
|---|---|---|
| author | Anton Astashov <anton.astashov@gmail.com> | Wed Jan 11 10:40:54 2017 -0600 |
| committer | Keerti Parthasarathy <keertip@users.noreply.github.com> | Wed Jan 11 08:40:54 2017 -0800 |
| tree | 790d725aaa633765211816008f3105321ec67639 | |
| parent | 7478a4f3d90f6e2d4f63db28e5f3cbf9040626d1 [diff] |
Add macros support [#1264] (#1320)
This adds pretty primitive macros support.
Usage:
You define the template first:
/// {@template foo}
/// Some content
/// {@endtemplate}
Then you use it like:
/// Some stuff
/// {@macro foo}
/// More stuff
and it will be displayed as:
/// Some stuff
/// Some content
/// More stuff
You can define the template pretty much in any documentable symbol
comments. So, after we build a `Package` object, we go through all the
comments documentation of all the model elements of the package, and
build the index of macros. It's still quite fast, and doesn't increase
the build times e.g. of the Flutter docs dramatically.
So, after that, when we actually build HTML pages, we already have the
index with templates in `Package`, so we can replace `{@macros` entries
with the corresponding contents from `{@template`
Use dartdoc to generate HTML documentaton for your Dart package.
For information about contributing to the dartdoc project, see the contributor docs.
For issues/details related to hosted Dart API docs, see dart-lang/api.dartlang.org.
bin directory to your PATHRun dartdoc from the root directory of package. For example:
$ dartdoc Generating documentation for 'server_code_lab' into <path-to-server-code-lab>/server_code_lab/doc/api/ parsing lib/client/piratesapi.dart... parsing lib/common/messages.dart... parsing lib/common/utils.dart... parsing lib/server/piratesapi.dart... Parsed 4 files in 8.1 seconds. generating docs for library pirate.messages from messages.dart... generating docs for library pirate.server from piratesapi.dart... generating docs for library pirate.utils from utils.dart... generating docs for library server_code_lab.piratesApi.client from piratesapi.dart... Documented 4 libraries in 9.6 seconds. Success! Docs generated into <path-to-server-code-lab>/server_code_lab/doc/api/index.html
By default, the documentation is generated to the doc/api directory as static HTML files.
Run dartdoc -h to see the available command-line options.
You can view the generated docs directly from the file system, but if you want to use the search function, you must load them with an HTTP server.
An easy way to run an HTTP server locally is to use the dhttpd package. For example:
$ pub global activate dhttpd $ dhttpd --path doc/api
Navigate to http://localhost:8080 in your browser; the search function should now work.
dartdoc produces static files with a predictable link structure.
index.html # homepage
index.json # machine-readable index
library-name/ # : is turned into a - e.g. dart:core => dart-core
ClassName-class.html # "homepage" for a class (and enum)
ClassName/
ClassName.html # constructor
ClassName.namedConstructor.html # named constructor
method.html
property.html
CONSTANT.html
property.html
top-level-function.html
File names are case-sensitive.
Check out the Effective Dart: Documentation guide.
The guide covers formatting, linking, markup, and general best practices when authoring doc comments for Dart with dartdoc.
dartdoc will not generate documentation for a Dart element and its children that have the @nodoc tag in the documentation comment.
You can specify “macros”, i.e. reusable pieces of documentation. For that, first specify a template anywhere in the comments, like:
/// {@template template_name}
/// Some shared docs
/// {@endtemplate}
and then you can insert it via {@macro template_name}, like
/// Some comment
/// {@macro template_name}
/// More comments
Please file reports on the GitHub Issue Tracker.
Please see the dartdoc license.