Dart documentation generator

Use dart doc to generate HTML documentation for your Dart package.

For information about contributing to the dartdoc project, see the [contributor docs][].

For issues/details related to the hosted Dart SDK API docs, see dart-lang/api.dart.dev.

Installation

The dart tool, with the dart doc command, is part of the Dart SDK.

Generating docs

Run dart doc . from the root directory of a package. You must first run dart pub get or flutter pub get and your package must analyze without errors with dart analyze or flutter analyze as appropriate. Here is an example of dartdoc documenting itself:

$ dart pub get
...
$ dart doc .
Documenting dartdoc...
...
Initialized dartdoc with 766 libraries in 63.9 seconds
Generating docs for library dartdoc from package:dartdoc/dartdoc.dart...
Validating docs...
no issues found
Documented 1 public library in 17.9 seconds
Success! Docs generated into <path to dartdoc>/doc/api

By default, the documentation is generated to the doc/api directory as static HTML files.

To view the generated documentation, you must load them with an HTTP server. To learn more, follow the Viewing docs guide.

Run dart help doc to see the available command-line options.

Viewing docs

To enable navigation and search, the generated docs must be served with an HTTP server.

An easy way to run an HTTP server locally is to use package:dhttpd. For example:

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

To then read the generated docs in your browser, open the link that dhttpd outputs, usually http://localhost:8080.

Link structure

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.

Writing docs

To learn about writing documentation comments, check out the Effective Dart: Documentation guide.

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

Excluding from documentation

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

Advanced features

dartdoc_options.yaml

Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc generates docs.

An example (not necessarily recommended settings):

dartdoc:
  categories:
    awesome:
      markdown: doc/First.md
      displayName: Awesome
    great:
      markdown: doc/Second.md
      displayName: Great
  categoryOrder: [awesome, great]
  includeExternal: ['bin/unusually_located_library.dart']
  nodoc: ['lib/sekret/*.dart']
  linkTo:
    url: "https://my.dartdocumentationsite.org/dev/%v%"
  showUndocumentedCategories: true
  ignore:
    - ambiguous-doc-reference
  errors:
    - unresolved-doc-reference
  warnings:
    - tool-error

dartdoc_options.yaml fields

In general, paths are relative to the directory of the dartdoc_options.yaml file in which the option is defined, and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. Unrecognized options will be ignored. Supported options:

• categories: A map from category names to category definitions. The category definition consists of a markdown: property and an optional displayName: property. For topics you'd like to document, specify a markdown file to be rendered on the category page, using the markdown: property. Optionally, you may specify a displayName: to be used in the rendered HTML, instead of the category name. Categories are referenced in documentation comments using the {@category <category name>} tag. Categories with no matching category name defined in dartdoc_options.yaml will be invisible.
• categoryOrder: A list of category names specifying the order of topics for display in the sidebar and the package page.
• exclude: Specify a list of library names to avoid generating docs for, overriding any specified in include. All libraries listed must be local to this package, unlike the command line --exclude. See also nodoc.
• errors: Specify warnings to be treated as errors. See the lists of valid warnings in the command line help for --errors, --warnings, and --ignore.
• favicon: A path to a favicon for the generated docs.
• footer: A list of paths to footer files containing HTML text.
• footerText: A list of paths to text files for optional text next to the package name and version
• header: A list of paths to header files containing HTML text.
• ignore: Specify warnings to be completely ignored. See the lists of valid warnings in the command line help for --errors, --warnings, and --ignore.
• include: Specify a list of library names to generate docs for, ignoring all others. All libraries listed must be local to this package (unlike the command line --include).
• includeExternal: Specify a list of library filenames to add to the list of documented libraries.
• linkTo: For other packages depending on this one, if this map is defined those packages will use the settings here to control how hyperlinks to the package are generated. This will override the default for packages hosted on pub.dev and api.flutter.dev.

  • url: A string indicating the base URL for documentation of this package. Ordinarily you do not need to set this in the package: consider --link-to-hosted and --link-to-sdks instead of this option if you need to build your own website with dartdoc.

    The following strings will be substituted in to complete the URL:

    • %b%: The branch as indicated by text in the version. 2.0.0-dev.3 is branch "dev". No branch is considered to be "stable".
    • %n%: The name of this package, as defined in pubspec.yaml.
    • %v%: The version of this package as defined in pubspec.yaml.
• linkToSource: Generate links to a source code repository based on given templates and revision information.

  • excludes: A list of directories to exclude from processing source links.

  • root: The directory to consider the 'root' for inserting relative paths into the template. Source code outside the root directory will not be linked.

  • uriTemplate: A template to substitute revision and file path information. If revision is present in the template but not specified, or if root is not specified, dartdoc will throw an exception. To hard-code a revision, don't specify it with %r%.

    The following strings will be substituted in to complete the URL:

    • %f%: Relative path of file to the repository root
    • %r%: Revision
    • %l%: Line number
• nodoc: Specify files (via globs) which should be treated as though they have the @nodoc tag in the documentation comment of every defined element. Unlike exclude this can specify source files directly, and neither inheritance nor reexports will cause these elements to be documented when included in other libraries. For more fine-grained control, use @nodoc in element documentation comments directly, or the exclude directive.
• warnings: Specify otherwise ignored or set-to-error warnings to simply warn. See the lists of valid warnings in the command line help for --errors, --warnings, and --ignore.

Unsupported and experimental options:

• ambiguousReexportScorerMinConfidence: The ambiguous reexport scorer will emit a warning if it is not at least this confident. Adjusting this may be necessary for some complex packages but most of the time, the default is OK. Default: 0.1

Categories

You can tag libraries or top level classes, functions, and variables in their documentation with the string {@category YourCategory}. For libraries, that will cause the library to appear in a category when showing the sidebar on the Package and Library pages. For other types of objects, the {@category} will be shown with a link to the category page but only if specified in dartdoc_options.yaml, as above.

/// Here is my library.
///
/// {@category awesome}
library my_library;

Other category tags and categories.json

A file categories.json will be generated at the top level of the documentation tree with information about categories collected from objects in the source tree. The directives @category, and @subCategory are understood and saved into this json.

As an example, if we document the class Icon in flutter using the following:

/// {@category Basics}
/// {@category