Repository files navigation

Usedart doc to generate HTML documentation for your Dart package.

For information about contributing to the dartdoc project, see thecontributor docs.

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

Thedart tool, with thedart doc command,is part of theDart SDK.

Rundart doc . from the root directory of a package.You must first rundart pub get orflutter pub get andyour package must analyze without errorswithdart analyze orflutter 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 secondsGenerating docs for library dartdoc from package:dartdoc/dartdoc.dart...Validating docs...no issues foundDocumented 1 public library in 17.9 secondsSuccess! Docs generated into <path to dartdoc>/doc/api

By default, the documentation is generated to thedoc/api directory asstatic HTML files.

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

Rundart help doc to see the available command-line options.

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

An easy way to run an HTTP server locally is to usepackage: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 thatdhttpd outputs, usuallyhttp://localhost:8080.

dartdoc produces static files with a predictable link structure.

index.html                          # homepageindex.json                          # machine-readable indexlibrary-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 arecase-sensitive.

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

The guide covers formatting, linking, markup, and general best practices whenauthoring doc comments for Dart withdart doc.

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

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

An example (not necessarily recommended settings):

dartdoc:categories:"First Category":markdown:doc/First.mdname:Awesome"Second Category":markdown:doc/Second.mdname:GreatcategoryOrder:["First Category", "Second Category"]includeExternal:['bin/unusually_located_library.dart']nodoc:['lib/sekret/*.dart']linkTo:url:"https://my.dartdocumentationsite.org/dev/%v%"showUndocumentedCategories:trueignore:    -ambiguous-doc-referenceerrors:    -unresolved-doc-referencewarnings:    -tool-error

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

• categories: More details for each category/topic. For topics you'd like to document, specifythe markdown file withmarkdown: to use for the category page. Optionally, rename thecategory from the source code into a display name withname:. If there is no matching categorydefined in dartdoc_options.yaml, those declared categories in the source code will be invisible.
• categoryOrder: Specify the order of topics for display in the sidebar andthe 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, unlikethe command line--exclude. See alsonodoc.
• errors: Specify warnings to be treated as errors. See the lists of valid warnings in the commandline 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 commandline help for--errors,--warnings, and--ignore.
• include: Specify a list of library names to generate docs for, ignoring all others. All librarieslisted 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 packageswill use the settings here to control how hyperlinks to the package are generated.This will override the default for packages hosted onpub.dev andapi.flutter.dev.

  • url: A string indicating the base URL for documentation of this package. Ordinarilyyou 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 withdartdoc.

    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 inpubspec.yaml.
    • %v%: The version of this package as defined inpubspec.yaml.
• linkToSource: Generate links to a source code repository based on given templates andrevision 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 revisionis present in the template but not specified, or if root is not specified, dartdoc willthrow 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@nodoctag in the documentation comment of every defined element. Unlikeexclude this can specifysource files directly, and neither inheritance nor reexports will cause these elements to bedocumented when included in other libraries. For more fine-grained control, use@nodoc inelement documentation comments directly, or theexclude directive.
• warnings: Specify otherwise ignored or set-to-error warnings to simply warn. See the listsof 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 ifit is not at least this confident. Adjusting this may be necessary for some complexpackages but most of the time, the default is OK. Default: 0.1

You can tag libraries or top level classes, functions, and variables in their documentation withthe string{@category YourCategory}. For libraries, that will cause the library to appear in acategory 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 pagebut only if specified indartdoc_options.yaml, as above.

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

A filecategories.json will be generated at the top level of the documentation tree withinformation 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 Assets and Icons}/// {@subCategory Information displays}classIconextendsStatelessWidget {}

that will result in the following json:

  {"name":"Icon","qualifiedName":"widgets.Icon","href":"widgets/Icon-class.html","type":"class","categories": ["Assets and Icons","Basics"    ],"subcategories": ["Information displays"    ],  }

You can specify links to videos inline that will be handled with a simple HTML5 player:

/// This widget is a dancing Linux penguin.////// {@animation name 100 200 http://host.com/path/to/video.mp4}

'name' is user defined, and the numbers are the width and height of the animation in pixels.

You can specify "macros", i.e. reusable pieces of documentation. For that, first specify a templateanywhere 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

Template definitions are currently unscoped -- if dartdoc reads a file containing a template, it can be used in anythingdartdoc is currently documenting. This can lead to inconsistent behavior between runs on differentpackages, especially if different command lines are used for dartdoc. It is recommended to use collision-resistantnaming for any macros by including the package name and/or library it is defined in within the name.

Libraries that are only referenced in documentation comments ([Future]) can be imported with a/// @docImport '<uri>' comment on thelibrary element, like:

/// @docImport 'dart:async';/// @docImport 'package:flutter/element.dart' show Element;/// @docImport '../path/to/somwhere.dart';/// @docImport 'dart:html' as 'html';library;/// We can now reference[Future] from dart:async,[Element] from Flutter's element library,/// and[html.Element] from dart:html, even if none of these libraries are actually imported/// by this library.classFoo {}

Dartdoc allows you to filter parts of the documentation through an external tooland then include the output of that tool in place of the given input.

First, you have to configure the tools that will be used in thedartdoc_options.yaml file:

dartdoc:tools:drill:command:["bin/drill.dart"]setup_command:["bin/setup.dart"]description:"Puts holes in things."compile_args:["--no-sound-null-safety"]echo:macos:['/bin/sh', '-c', 'echo']setup_macos:['/bin/sh', '-c', 'setup.sh']linux:['/bin/sh', '-c', 'echo']setup_linux:['/bin/sh', '-c', 'setup.sh']windows:['C:\\Windows\\System32\\cmd.exe', '/c', 'echo']setup_windows:['/bin/sh', '-c', 'setup.sh']description:'Works on everything'

Thecommand tag is used to describe the command executable, and any optionsthat are common among all executions. If the first element of this list is afilename that ends in.dart, then the dart executable will automatically beused to invoke that script. Thecommand defined will be run on all platforms.

If thecommand is a Dart script, then the first time it is run, a snapshotwill be created using the input and first-time arguments as training arguments,and will be run from the snapshot from then on. Note that thePlatform.scriptproperty will point to the snapshot location during the snapshot runs. You canobtain the original.dart script location in a tool by looking at theTOOL_COMMAND environment variable.

Thesetup_command tag is used to describe a command executable, and anyoptions, for a command that is run once before running a tool for the firsttime. If the first element of this list is a filename that ends in.dart, thenthe dart executable will automatically be used to invoke that script. Thesetup_command defined will be run on all platforms. If the setup command is aDart script, then it will be run with the Dart executable, but will not besnapshotted, as it will only be run once.

Themacos,linux, andwindows tags are used to describe the commands to berun on each of those platforms, and thesetup_macos,setup_linux, andsetup_windows tags define setup commands for their respective platforms.

Thedescription is just a short description of the tool for use as help text.

Only tools which are configured in thedartdoc_options.yaml file are able tobe invoked.

Thecompile_args tag is used to pass options to the dart compiler when thefirst run of the tool is being snapshotted.

To use the tools in comment documentation, use the{@tool <name> [<options> ...] [$INPUT]} directive to invoke the tool:

/// {@tool drill --flag --option="value" $INPUT}/// This is the text that will be sent to the tool as input./// {@end-tool}

The$INPUT argument is a special token that will be replaced with the name ofa temporary file that the tool needs to read from. It can appear anywhere in theoptions, and can appear multiple times.

If the exampledrill tool with those options is a tool that turns the contentof its input file into a code-font heading, then the directive above would bethe equivalent of having the following comment in the code:

/// #`This is the text that will be sent to the tool as input.`

Tools have a number of environment variables available to them. They will beinterpolated into any arguments given to the tool as$ENV_VAR or$(ENV_VAR),as well as available in the process environment.

• SOURCE_LINE: The source line number in the original source code.
• SOURCE_COLUMN: The source column in the original source code.
• SOURCE_PATH: The relative path from the package root to the original source file.
• PACKAGE_PATH: The path to the package root.
• PACKAGE_NAME: The name of the package.
• LIBRARY_NAME: The name of the library, if any.
• ELEMENT_NAME: The name of the element that this doc is attached to.
• TOOL_COMMAND: The path to the original.dart script or command executable.
• DART_SNAPSHOT_CACHE: The path to the directory containing the snapshot filesof the tools. This directory will be removed before Dartdoc exits.
• DART_SETUP_COMMAND: The path to the setup command script, if any.
• INVOCATION_INDEX: An index for how many times a tool directive has beeninvoked on the current dartdoc block. Allows multiple tool invocations on thesame block to be differentiated.

It rarely happens, but sometimes what you really need is to inject some raw HTMLinto the dartdoc output, without it being subject to Markdown processingbeforehand. This can be useful when the output of an external tool is HTML, forinstance. This is where the{@inject-html}...{@end-inject-html} tags come in.

For security reasons, the{@inject-html} directive will be ignored unless the--inject-html flag is given on the dartdoc command line.

Since this HTML fragment doesn't undergo Markdown processing, reference linksand other normal processing won't happen on the contained fragment.

So, this:

///     {@inject-html}  ///<p>[The HTML to inject.]()</p>  ///{@end-inject-html}

Will result in this be emitted in its place in the HTML output (notice that themarkdown link isn't linked).

<p>[The HTML to inject.]()</p>

It's best to only inject HTML that is self-contained and doesn't depend uponother elements on the page, since those may change in future versions of Dartdoc.

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

The source linking feature in dartdoc is a little tricky to use, since pub packages do not actuallyinclude enough information to link back to source code and that's the context in which documentationis generated for the pub site. This means that for now, it must be manually specified indartdoc_options.yaml what revision to use. It is currently a recommended practice tospecify a revision in dartdoc_options.yaml that points to the same revision as your public package.If you're using a documentation staging system outside of Dart's pub site, override the template andrevision on the command line with the head revision number. You can use the branch name,but generated docs will generate locations that may start drifting with further changes to the branch.

Example dartdoc_options.yaml:

linkToSource:root:'.'uriTemplate:'https://github.com/dart-lang/dartdoc/blob/v0.28.0/%f%#L%l%'

Example staging command line:

dart pub global run dartdoc --link-to-source-root'.' --link-to-source-revision 6fac6f770d271312c88e8ae881861702a9a605be --link-to-source-uri-template'https://github.com/dart-lang/dartdoc/blob/%r%/%f%#L%l%'

This gets more complicated with--auto-include-dependencies as these command line flagswill override all settings from individual packages. In that case, to preservesource links from third party packages it may be necessary to generatedartdoc_options.yaml options for each package you are intending to add source linksto yourself.

Please file reports on theGitHub Issue Tracker. Issues are labeled withpriority based on how much impact to the ecosystem the issue addresses andthe number of generated pages that show the anomaly (widespread vs. notwidespread).

Some examples of likely triage priorities:

• P0

  • Broken links, widespread
  • Uncaught exceptions, widespread
  • Incorrect linkage outside of comment references, widespread
  • Very ugly or navigation impaired generated pages, widespread
  • Generation errors for high priority users (Flutter, Pub, Fuchsia, Dart),widespread and/or blocking critical teams

• P1

  • Broken links, few or on edge cases
  • Uncaught exceptions, very rare or with simple workarounds
  • Incorrect linkage outside of comment references, few or on edge cases
  • Incorrect linkage in comment references, widespread or with high impact
  • 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 errors that should be detected but aren't warned, widespread
  • Enhancements that have significant data around them indicating they are abig win
  • User performance problem (e.g. page load, search), widespread
  • Generation errors for high priority users (Flutter, Pub, Fuchsia, Dart),not widespread or blocking critical teams

• P2

  • Incorrect doc contents, not widespread
  • Incorrect linkage in comment references, not widespread
  • Minor display warts not significantly impeding navigation, not widespread
  • Generation problems that should be detected but aren't warned, notwidespread
  • Default-on warnings that are misleading or wrong, few or on edge cases
  • Non-default warnings that are misleading or wrong, widespread
  • Enhancements considered important but without significant data indicatingthey are a big win
  • User performance problem (e.g. page load, search), not widespread
  • Generation performance problem, widespread

• P3

  • Theoretical or extremely rare problems with generation
  • Minor display warts on edge cases only
  • Non-default warnings that are misleading or wrong, few or on edge cases
  • Enhancements whose importance is uncertain
  • Generation performance problem, limited impact or not widespread

Please see thedartdoc license.

Generated docs include:

• Highlight.js -LICENSE
  • Withgithub.css (c) Vasily Polovnyovvast@whiteants.net