Text of github.com › dart-lang › dartdoc as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

GitHub - dart-lang/dartdoc: API documentation tool for Dart. · GitHub

Skip to content You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert Branches Tags Open more actions menu Latest commit History 3,527 Commits 3,527 Commits Folders and files Name Name Last commit message Last commit date .github .github bin bin doc doc example example lib lib test test testing testing tool tool web web .gitattributes .gitattributes .gitignore .gitignore .pubignore .pubignore AUTHORS AUTHORS CHANGELOG.md CHANGELOG.md CONTRIBUTING.md CONTRIBUTING.md GEMINI.md GEMINI.md LICENSE LICENSE README.md README.md analysis_options.yaml analysis_options.yaml dartdoc_options.yaml dartdoc_options.yaml pubspec.yaml pubspec.yaml Repository files navigation 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 . The resulting URL must be a plain http: or https: URL; anything else (a relative URL, a javascript: URL, a value containing quotes or angle brackets, ...) is ignored with an invalid-url warning, and no links to the package are generated. 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 The resulting URL must be a plain http: or https: URL; anything else (a relative URL, a javascript: URL, a value containing quotes or angle brackets, ...) is ignored with an invalid-url warning,

The rest of this page is on the live site.