Writing docs

The guide covers formatting, linking, markup, and general best practices when
authoring doc comments for Dart with dartdoc.

Excluding from documentation

dartdoc will not generate documentation for a Dart element and its children that have the
@nodoc tag in the documentation comment.

Advanced features

Macros

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

Auto including dependencies

If --auto-include-dependencies flag is provided, dartdoc tries to automatically add
all the used libraries, even from other packages, to the list of the documented libraries.

Issues and bugs

Please file reports on the GitHub Issue Tracker. Issues are labeled with
priority based on how much impact to the ecosystem the issue addresses and
the number of generated pages that show the anomaly (widespread vs. not
widespread).

Some examples of likely triage priorities:

P0

Broken links, widespread

Uncaught exceptions, widespread

Incorrect linkage, widespread

Very ugly or navigation impaired generated pages, widespread

P1

Broken links, few or on edge cases

Uncaught exceptions, very rare or with simple workarounds

Incorrect linkage, few or on edge cases

Incorrect doc contents, widespread or with high impact

Minor display warts not significantly impeding navigation, widespread

Default-on warnings that are misleading or wrong, widespread

Generation problems that should be detected but aren't warned, widespread

Enhancements that have significant data around them indicating they are a big win