dartdoc 0.30.3

  • Readme
  • Changelog
  • Example
  • Installing
  • 87

dartdoc #

Build Status Appveyor Build Status Coverage Status

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.dart.dev.

Installing dartdoc #

  • download the Dart SDK
  • add the SDK's bin directory to your PATH

Generating docs #

Run 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.

Viewing docs #

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.html                  # constructor
    ClassName.namedConstructor.html # named constructor

File names are case-sensitive.

Writing docs #

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.

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 #

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):

    "First Category":
      markdown: doc/First.md
      name: Awesome
    "Second Category":
      markdown: doc/Second.md
      name: Great
  categoryOrder: ["First Category", "Second Category"]
  examplePathPrefix: 'subdir/with/examples'
  includeExternal: ['bin/unusually_located_library.dart']
    url: "https://my.dartdocumentationsite.org/dev/%v%"
  showUndocumentedCategories: true
    - ambiguous-doc-reference
    - unresolved-doc-reference
    - tool-error

Unrecognized options will be ignored. Supported options:

  • categories: More details for each category/topic. For topics you'd like to document, specify the markdown file with markdown: to use for the category page. Optionally, rename the category from the source code into a display name with 'name:'. If there is no matching category defined 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 and the package page.
  • examplePathPrefix: Specify the location of the example directory for resolving @example directives.
  • exclude: Specify a list of library names to avoid generating docs for, overriding any specified in include.
  • 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.
  • 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.
    • 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
  • 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.

In general, paths are relative to the directory the dartdoc_options.yaml the option is defined in and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows.

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 Amazing}
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, @subCategory, @image, and @samples are understood and saved into this json. Future versions of dartdoc may make direct use of the image and samples tags.

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

/// {@category Basics}
/// {@category Assets, Images, and Icons}
/// {@subCategory Information displays}
/// {@image <image alt='' src='/images/catalog-widget-placeholder.png'>}
class Icon extends StatelessWidget {}

that will result in the following json:

    "name": "Icon",
    "qualifiedName": "widgets.Icon",
    "href": "widgets/Icon-class.html",
    "type": "class",
    "categories": [
      "Assets, Images, and Icons",
    "subcategories": [
      "Information displays"
    "image": "<image alt='' src='/images/catalog-widget-placeholder.png'>"

Animations #

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.

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

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

Tools #

Dartdoc allows you to filter parts of the documentation through an external tool and 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 the dartdoc_options.yaml file:

      command: ["bin/drill.dart"]
      setup_command: ["bin/setup.dart"]
      description: "Puts holes in things."
      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'

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

If the command is a Dart script, then the first time it is run, a snapshot will be created using the input and first-time arguments as training arguments, and will be run from the snapshot from then on. Note that the Platform.script property will point to the snapshot location during the snapshot runs. You can obtain the original .dart script location in a tool by looking at the TOOL_COMMAND environment variable.

The setup_command tag is used to describe a command executable, and any options, for a command that is run once before running a tool for the first time. If the first element of this list is a filename that ends in .dart, then the dart executable will automatically be used to invoke that script. The setup_command defined will be run on all platforms. If the setup command is a Dart script, then it will be run with the Dart executable, but will not be snapshotted, as it will only be run once.

The macos, linux, and windows tags are used to describe the commands to be run on each of those platforms, and the setup_macos, setup_linux, and setup_windows tags define setup commands for their respective platforms.

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

Only tools which are configured in the dartdoc_options.yaml file are able to be invoked.

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 of a temporary file that the tool needs to read from. It can appear anywhere in the options, and can appear multiple times.

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

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

Tool Environment Variables

Tools have a number of environment variables available to them. They will be interpolated 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 files of 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 been invoked on the current dartdoc block. Allows multiple tool invocations on the same block to be differentiated.

Injecting HTML #

It happens rarely, but sometimes what you really need is to inject some raw HTML into the dartdoc output, without it being subject to Markdown processing beforehand. This can be useful when the output of an external tool is HTML, for instance. 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 links and 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 the markdown 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 upon other elements on the page, since those may change in future versions of Dartdoc.

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.

The source linking feature in dartdoc is a little tricky to use, since pub packages do not actually include enough information to link back to source code and that's the context in which documentation is generated for the pub site. This means that for now, it must be manually specified in dartdoc_options.yaml what revision to use. It is currently recommended practice to specify 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 and revision 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:

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

Example staging command line:

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 flags will override all settings from individual packages. In that case, to preserve source links from third party packages it may be necessary to generate dartdoc_options.yaml options for each package you are intending to add source links to yourself.

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
    • User performance problem (e.g. page load, search), widespread
  • P2

    • Incorrect doc contents, not widespread
    • Minor display warts not significantly impeding navigation, not widespread
    • Generation problems that should be detected but aren't warned, not widespread
    • 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 indicating they 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

License #

Please see the dartdoc license.

Generated docs include:

0.30.3 #

  • Add support for Never type from analyzer (#2167, #2170).
  • First markdown renderers landed (#2152) and dartdoc can sometimes generate markdown, but it is not ready for prime-time yet.

0.30.2 #

  • Fix the broken search box with --use-base-href in Flutter (#2158).
  • More internal changes preparing for markdown output (#2145, #2150, #2151, #2153).

0.30.1 #

  • A more complete fix for the broken search box. (#2125, #2124)
  • Fix the "--rel-canonical-prefix" flag post base href. (#2126, #2122)
  • Tool change: grind serve-pub-package can now serve packages depending on flutter for debugging purposes (#2130)
  • More internal changes preparing for markdown output (#2138, #2140, #2132, #2121, #2115)
  • Fix a crash when using --no-generate-docs (#2139)

0.30.0+1 #

  • Fix a broken search box on pages in subdirectories (#2117, #2118)

0.30.0 #

  • BREAKING CHANGE: no longer use <base href> in generated documentation, instead use real relative links. This may break manually constructed links that rely on base href, or could impact post-processing of dartdoc HTML. Most users should not notice. A hidden flag can for now restore the old behavior, but will be removed soon. (#2098, #2096)
  • More refactors to prepare for markdown rendering. (#2100, #2114)
  • Fix crashes with extensions on special types. (#2112, #2102)
  • Add a new error type for multiple-file overwrite problems. (#2111, #2110)
  • Allow FunctionTypes to work in applicability checks for extensions. (#2109, #2101)
  • Refactor to use Element.declaration over Member.baseMember. (#2106)

0.29.3 #

  • More refactoring changes to rendering (#2085, #2086).
  • Internal changes to stop using newly deprecated analyzer interfaces (#2091, #2093).

0.29.2 #

  • Many refactoring changes to rendering and tests (#2084, #2081, #2080, #2078, #2077, #2076, #2068, #2067).
  • Add 'required' for required named parameters with NNBD enabled (#2075).
  • Rewrite parameter handling and fix problems with brackets (#2075, #2059, #2052, #2082).
  • Add 'late' as a feature for final variables with NNBD enabled (#2071).
  • Add presubmit grinder and dartfmt check for dartdoc development (#2070).
  • Initial implementation of NNBD support (with --enable-experiment flag) (#2069).

0.29.1 #

  • Fix edge cases on extension discovery (#2062).
  • Make sure that enum documentation contains unique IDs for animations (#2060).

0.29.0 #

  • Internal change to our use of FunctionTypeAliasElement for the analyzer (#2051).
  • Analyzer version to 0.29+ (#2049).
  • Refactor element discovery and fix extension discovery to work with imports (#2050).
  • Bugfix for corrupt location reporting in many cases (#2043).
  • Add a list of extensions to applicable class pages (#2053).

0.28.8 #

  • Use analyzer line number library, fixing crash on empty file (#2034, #1938).
  • Fix crash on resolving comment references inside extension methods (#2040, #2033).

0.28.7 #

  • Remove obsolete references to Element.type and ElementHandle (#2028, #2031).
  • Fix problem with return values for typedefs with analyzer 0.38.5 (#2036).

0.28.6 #

  • Support for 0.38.3 version of package:analyzer.
  • Support generating docs for extension methods (#2001).

0.28.5 #

  • Support the latest version of package:analyzer.
  • Fix hyperlinks to overriden methods (#1994).
  • Option in dartdoc_options.yaml to exclude version in footer info (#1982).

0.28.4 #

  • Breaking change Change the default for allow-tools command line flag to false.
  • Fix some lints.
  • Update to support a future version of analyzer.

0.28.3+3 #

  • Fix code highlighting in Dart after string interpolation (#1946, #1948) by updating the highlightjs dependency.
  • Fix indentation of inheritance info to match others

0.28.3+2 #

  • Support the latest version of package:html.
  • Use latest version of the markdown package.

0.28.3+1 #

  • Fix scroll physics and behavior for Safari on iOS.

0.28.3 #

  • Support a new {@youtube} directive in documentation comments to embed YouTube videos.

0.28.2 #

  • Add empty CSS classes in spans around the names of entities so Dashing can pick them up. (flutter/flutter#27654, #1929)
  • Test fixups for experiments (#1932, #1931, #1929).
  • Make precaching work for borrowed documentation, fixing cases where @tool directives were not being substituted correctly in generated docs (#1930, #1934).

0.28.1+2 #

  • Fix alignment of search box text in Safari (#1926).

0.28.1+1 #

  • Make hamburger menu appear in Chrome 72.

0.28.1 #

  • Reenable three-pane scrolling in Chrome 72 (#1922, #1921)
  • A new version of the highlightjs pack supports syntax highlighting for SCSS. (#1906, #1907)
  • Allow manually-specified links to source code, appearing as a small icon near the top of each element's page (#1913, #1454, #1892)
  • Dartdoc can be used just to generate warnings by passing --no-generate-docs (#1909, #1537).
  • Dartdoc's default CSS now more closely resembles dartlang.org, with some miscellaneous alignment tweaks, Roboto font, and use of :hover to highlight links (#1916, #1372)
  • Viewport parameters for mobile now prevent "stuck page" syndrome (#1916, #1911). Overscroll is now permitted for mobile.
  • Fix a problem where we don't render greater than symbols in the header for Chrome 72 (#1919, #1918)
  • Dartdoc now remembers scroll positions for all three columns while navigating (#1917, #1288, #1372, #779, #1870)
  • Update analyzer package to 0.35.0 and several internal test/coverage infrastructure fixes.

0.28.0 #

  • Fix a crash when a Dart library doesn't have the .dart suffix (#1897)
  • Fix a crash when a Dart file is loaded with an unresolvable prefix import in analyzer (#1896)
  • Do not execute tools to generate documentation for non-canonical elements that have canonical counterparts. This eliminates "duplicate" tool runs that serve no purpose for generated docs or macro loading. (#1898)
  • Fix a minor problem where invalid command line parameters could generate an ugly exception (#1895)
  • Remove internal copy of mustache4dart and depend on the mustache package. Many minor changes to templating as a result. (#1894)
  • Breaking change to warning handling. Many new command line options and dartdoc_options.yaml settings can constrain and configure how warnings are interpreted by dartdoc, and whether they are fatal. The old --show-warnings flag has been removed. (#1891, #1343, #1412, #1480)
  • Fix a crash when loading README.md files that have invalid UTF-8. (#1890, #1889)
  • Early implementation of experiment flags for Dart tools, based on the analyzer (#1884)

0.27.0 #

  • Several dartdoc project infrastructure changes, including coverage support. (#1869, #1878, #1879, #1881, #1882)
  • Fixed many issues that made mobile/small screen usage of dartdoc impossible. Mobile users should now be able to do basic browsing and searching in API docs. (#1873, #908, #1048, #1348, #1469)
  • Support import prefix resolution in dartdoc. (#1875, #1402).

0.26.1 #

  • Fix bug that accidentally caused dartdoc to create (and overwrite with) multiple snapshots in parallel for a single tool (#1861, #1862)
  • Refactor comment reference handling for performance and readability (#1863)
  • Simplify temp file creation and reduce the amount of filesystem churn for tools (#1865)
  • Reenable testing for flutter plugin doc generation (This requires a Flutter SDK with flutter/flutter#25243 to work with tools enabled). Flutter plugin doc generation now requires your flutter installation to have 'flutter update-packages' run on it before it will work.

0.26.0 #

  • Remove crossdart support (#1856)
  • Launch helper tools and construct PackageGraphs asynchronously (#1849)
  • Refactor Dartdoc to avoid use of analyzer's computeNode, and prevent it from holding on to fully resolved ASTs from analyzer (#1851, #1857, #1858)
  • Dartdoc no longer attempts to report analysis errors but assumes they will be non-fatal and carries on (#1845)
  • Add command line flag to allow disabling tools (#1853)

0.25.0 #

  • Fix crash if a code reference ambiguously referred to a parameter of an optional function parameter (#1835, #1841)
  • Allow annotations that return the dynamic type (#1834, #1840)
  • Better error messages in the case of a package with no documentable libraries (#1832)
  • Fix a problem where the reexport tagger could trigger stack overflow if a library exported itself (#1832, #1838)
  • Performance-related refactorings to return some of the performance lost with macro templates in private libraries (#1828, #1829, #1831, #1837)
  • Fix several Flutter problems (#1819)
    • Fix assertion failure if macros are defined in packages with no public libraries
    • Allow declaring macro templates in private libraries
    • Avoid circular dependency in finding special objects
    • Populate reference cache with child elements of mixins (fixes ~45 links inside Flutter)
  • Added support for automatic snapshotting of external tools (i.e. for {@tool} directives) written in Dart. (#1820)
  • Changes to reduce use of internal APIs in analyzer (#1817, #1825)
  • Template text now appears where it is defined in addition to where it is referenced (#1812)
  • Change placeholder string in search box to 'Search API Docs'
  • Fix some instances where macros were not being resolved correctly (#1811)
  • Macro templates now appear where they are defined in addition to where they are referenced (#1810)

0.24.1 #

  • Added more metadata (element name, project name, etc.) to external tool invocations. (#1801)
  • Fixed a bug where not specifying --show-warnings caused dartdoc to report success even when errors were present. (#1805)

0.24.0 #

  • Add 'override' to feature list for members which override a superclass (#981)
  • Support many options via dartdoc_options.yaml (#1674)
  • Allow insertion of raw HTML into dartdoc, via flag (#1793)
  • Stop using old supermixin syntax in dartdoc (#1772)

0.23.1 #

  • Make mixins appear under their own category, even if they are reexported (#1785)

0.23.0 #

  • Document covariant parameters and fields (#1782)
  • Implement new-style mixin support for Dart 2.1 (#1765, #1752, #1778, #1779)
  • Remove direct dependency on front_end package (#1780)
  • Travis/testing and grinder script changes (#1777, #1771)
  • Captions on class pages now use nouns consistently (#1767)
  • Minor changes to categories style (#1761)

0.22.0 #

  • Documentation updates. (#1760)
  • Fix incompatibility with head analyzer (endsWith exception). (#1768)
  • Added the ability to run external tools on a section of documentation and replace it with the output of the tool.

0.21.1 #

  • Fix a problem where category ordering specified in categories option was not obeyed. Reintroduce categoryOrder option to solve this problem.

0.21.0 #

  • Expand categories to all top level items as well as libraries. (#1681, #1353)
  • The categoryOrder option in dartdoc_options.yaml and the command line is replaced with a more generic "categories" option. See README.md.

0.20.4 #

  • Hide pragma declarations from generated docs (#1726)
  • Fix problems with lists in markdown not being handled correctly (#172)
  • Properly escape types inside comment references (#1740)
  • Generate a custom page, __404error.html, for use as an error page (#1704)
  • Generate an error on unresolved exports instead of crashing (#1745)
  • Generate anchors for headers in markdown (#1749)

0.20.3 #

  • Update dependencies and fork mustache4dart into dartdoc so dartdoc can resolve dependencies on Dart 2.0 stable.

0.20.2 #

  • Fix void problems (#1724)
  • Fix crash building Angular docs and problems involving special objects (#1728, #1554)
  • Run pub upgrade to get packages ready for 69.2.

0.20.1 #

  • Remove name parameter from @animation parameter handling, with backwards compatibility (#1715)
  • Scrollbar width increased for main body text (#1711)
  • Make a missing FLUTTER_ROOT environment variable have a better error message (#1714)
  • Add a missing static resource (#1708)
  • Add test to make sure that static resource file is automatically rebuilt (#1708)

0.20.0 #

  • include and exclude are now available in dartdoc_options.yaml as supported options (#1700, #1674)
  • Support a new {@animation} directive in documentation comments to display videos in a simple player.
  • Fix Dart 2.0 support (#1668) and expand test coverage to include --help.

0.19.1 #

  • Update package:markdown to 2.0.0, which includes many improvements – especially to the parsing of links.
  • Update analyzer to 0.32.0, mustache4dart to 2.1.2, and grinder for 0.8.2 for Dart 2 fixes.
  • Fix bug where --version printed help instead of the version number. (#1692)
  • Switch dartdoc_test to an integration test and add basic Dart 2.0 integration tests.
  • Do not crash on unversioned packages (#1688).

0.19.0 #

  • Build documentation through the Package object (#1659)
  • New flag, --link-to-remote, which will cause Dartdoc to link symbols to their originating pub packages and/or the Flutter or Dart SDKs. (#739)
  • New configuration refactor and addition of several experimental options in dartdoc_options.yaml (see README).
  • Update analyzer version to 0.31.2-alpha.2 (#1682).

0.18.1 #

  • Fix problems with the embedded SDK detection that cropped up in the package refactor (#1648, #1651)
  • Fix issues with anonymous functions and type parameters (#1651)
  • Add Menlo to the monospace font list to improve table formatting (#1647)

0.18.0 #

  • Rename category_order flag to package_order. (#1634, #1636)
  • Use Google's CDN for jquery. (#1637)
  • Add the beginning of support for a dartdoc_options.yaml file. (#1638)
  • Code cleanups and refactoring related to packages (#1639, #1636)
  • Enable --preview-dart-2 in analyzer (#1630)
  • Add basic categorization for libraries (#1641)

0.17.1+1 #

  • Fix pub warning regarding unnecessary meta import.

0.17.1 #

  • Fix rendering of bold markdown (#1618)
  • Internal cleanups and refactors (#1626, #1624, #1622)
  • Support void as a type parameter (#1625)

0.17.0 #

  • More correctly deal with indentation inside documentation comments, fixing a set of minor markdown problems relating to indentation (like list handling) (#1608, #1507)
  • Strong mode enabled in dartdoc -- dartdoc will no longer read code that isn't strong-mode clean beginning with this version. (#1561)
  • Add a negatable flag (default on), --validate-links, to control whether Dartdoc's built-in link checker runs. (#1607)
  • dartdoc now works in checked mode for Flutter, fixing some edge-case navigation/canonicalization problems. (#1606)
  • Dartdoc now uses AnalysisDriver to build the element tree. (#1601, #1586)
  • Grinder now has arbitrary serving of pub packages and can compare warnings from different versions (#1600, #1599)

0.16.0 #

  • Cherrypick test changes from 0.15.1 and a fix for (#1603), updating dartdoc to the latest analyzer.

0.15.1 #

  • Add SDK warning comparison to grind script (#1572)
  • Improve rendering of inline <code> (#1573)
  • Rename "Source Code" to "Implementation" (#1580)
  • Make page titles more prominent (#1581)
  • Detect macros declared in non-public symbols (#1584)
  • Const value cosmetic improvements with some restored linking (#1585)
  • Update to latest versions of args, resource, grinder (#1566, #1579)
  • Update to grinder scripts to serve flutter, SDK, and the test package locally for testing (#1570, #1578)

0.15.0+1 #

  • Move sdk_footer_text to resources directory for compatibility with SDK build system (#1563)

0.15.0 #

  • Breaking change: Major internal refactoring of public/private, type definitions, templates, and warnings. (#1524, #1539)
  • Breaking change: Allow mixins that call their super-classes. (#1555)
  • Breaking change: Anonymous libraries are now laid out on disk differently to avoid conflicts (#1526)
  • Breaking change: The meaning of --auto-include-dependencies has changed to include all libraries in any package depended on by this package (determined by the .packages file) (#1524)
  • Breaking change: The meaning of --include and --exclude has changed to require import paths for anonymous libraries, and accept them for other libraries. (#1524)
  • The Interceptor class from the SDK is now cloaked (#1524)
  • Type parameters for classes now appear next to them on the library page (#1558)
  • GFM-style tables are now supported in Dartdoc markdown (#1557, #1453)
  • Navigation and constructor docs now show generic types in more places (#1556, #1453)
  • A new parameter, --exclude-packages, now enables dartdoc to hide entire packages from --auto-include-dependencies or other --include options.
  • Document correct parameters for new-style generic function types (#1472)
  • Allow super in mixins (#1541)
  • Source code included with docs highlights again (#1525)
  • Remove constant value linking via string substitution (#1535)
  • Update version of mustache4dart and fix minor template errors (#1540)
  • Eliminate remaining places where dartdoc exposed private interfaces (#1173)
  • Fix private super classes appearing with dead links (#1476)
  • Fix resolution of generic types (#1514)
  • Limit width of code blocks (#1522)
  • Add a --json flag to providing logging in a machine-readable format. (#1531)
  • Use the logging package for dartdoc output. (#1518)
  • Remove cc commons license text from default footer (#1262)

0.14.1 #

  • Add better support for GenericFunctionTypeElementImpl (#1506, #1509)
  • Fix up dartdoc so it can be used with the head analyzer again (#1509)
  • SDK constraint fixed (#1503)

0.14.0 #

  • Fix multiple issues with properties and top level variables in cases of split inheritance (#1394, #1116)
  • Fix issue with generation of 'null' value enum fields (#1445)
  • Fix multiple issues with nodoc handling (#1352, #1337)
  • Use highlight js for code blocks and fix colors (#1487)
  • Eliminate excessive stack depth in link checker
  • Use preferredClass in more cases to disambiguate doc links
  • Add basic support and tests for MultiplyInheritedExecutableElements (#1478)

0.13.0+3 #

  • Add support for GenericFunctionTypeElementImpl (#1495)

0.13.0+2 #

  • Allow null annotation elements (#1491)

0.13.0+1 #

  • Remove unnecessary dependency on meta.
  • Drop --force from pub publish arguments to avoid publishing more broken packages.

0.13.0 #

  • Fixed case where inherited members could be linked to the wrong mixin (#1434)
  • Added broken link detection to the search index.
  • Avoid parsing markdown for ModelElements unless we're actually going to use the docs, speeding up generation overall by ~10% (#1417)
  • Add annotations to parameter documentation (#1432)
  • Change dartdoc style to use multiple independent scrolling columns (#1350)
  • Add scoring for ambiguous canonicalization, and a new comment directive, canonicalFor, to override its decisions (#1455)
  • Add a hidden flag to drop text in docs imported from the SDK, and use this flag in the integration test to make that test less fragile (#1457)
  • Add link to package homepage from index (#1460)

0.12.0 #

  • Generation performance improved from 20-65% on large packages (more improvement on packages with lower usage of comment references and complex inheritance chains, like angular2).
  • Improvements to warnings, including indicating referring elements where possible. #1405
  • Enable support for generic function types. #1321
  • Update analyzer to 0.30. #1403
  • Enhancements to css style to better match dartlang.org. #1372 (partial)

0.11.2 #

  • Fix regression where warnings generated by the README could result in a fatal exception. #1409

0.11.1 #

  • Fix regression where a property or top level variable can be listed twice under some conditions. #1401

0.11.0 #

  • Fix resolution of ambiguous classes where the analyzer can help us. #1397
  • Many cleanups to dartdoc stdout/stderr, error messages, and warnings:
    • Display fatal errors with 'fatal error' string to distinguish them from ordinary errors
    • Upgrades to new Package.warn system.
      • Fully integrated all scattered "warnings" (#1369) and added new ones for the link checker.
      • Allow for setting which warnings are errors in the library.
      • Change location output to something IntelliJ can understand and link to
      • Display location output for all warnings including line number plus column, when available from analyzer (still some bugs in our resolution). It still doesn't do code references quite right but at least gets you to the neighborhood.
      • Add a warn method to ModelElements so they can warn on themselves without help from the Package.
      • Warn correctly and squelch duplicates across doc inheritance and canonicalization almost everywhere.
      • Change --show-warnings to show all warnings, even those that might not be useful yet.
    • Display a count of all warnings/errors after document generation.
    • Make the progress counter tick slower.
  • Added a built-in link checker and orphaned file checker, and tied it into Package.warn so that when debugging dartdoc we can breakpoint and discover what about that ModelElement caused us to create the broken link. (#1380)
  • Fix bug where canonicalEnclosingElement could return a non-canonical Class.
  • Fix bug where findCanonicalModelElementFor could return a non-canonical Class.
  • Fix overriddenElement for Accessors to generate using enclosingCombo hint to ModelElement factory.
  • Fix fullyQualifiedNameWithoutLibrary when periods are part of the library name.
  • Add an allModelElements for Classes to support comment references.
  • Make allModelElements for Libraries work using Class.allModelElements recursively.
  • Squish some bugs related to duplicate logic for instantiating inherited class members.
    • Enum and a few other places could still generate duplicate ModelElements for the same thing. This is now fixed.
    • EnumField is now handled by ModelElement.from factory, fixing #1239.
    • Added hints for EnumField and Accessors (index, enclosingCombo) to offload the buggy logic for figuring this out from callers to ModelElement.from.
  • Fix broken link generation when a canonical class's defining library isn't canonical.
  • Partial rewrite of GetterSetterCombo and Fields/TopLevelVariable handling
    • Link correctly to generic types for Fields/TopLevelVariables.
    • Use right, left, and bidirectional arrows for read-only, write-only, and read-write parameters.
  • Partial rewrite of comment reference system (#1391, #1285 partial)
    • Handle gracefully a variety of things users try in the real world, like prefixing operators with 'operator', embedded newlines in comment references, and cases that shouldn't be considered at all (comment refs that are really array references in sample docs, etc).
    • Handle canonicalization correctly for comment references: point to the right places and only to canonical elements.
    • In general, warnings related to comment references should be much more useful now. (#1343)
      • Many fewer ambiguous doc reference warnings now and the ones that exist should be more easily understandable and fixable with the new warning message.
      • Understand references to parameters even though we don't do anything useful with them just yet
      • Generics outside square brackets (#1250) are now warned with better context information that takes newlines into account, but there are so many of them in complex packages like Flutter that we still only show those with --show-warnings.
    • Cache the traversal of allModelElements.
    • Change handling of enum constant linking in codeRefs to work properly, though warnings about that aren't right in some edge cases still.
    • Only use analyzer resolving of commentRefs as a last resort since they don't take dartdoc canonicalization into account.
  • Added a new --footer-text command-line option, to allow adding additional text in the package name and copyright section of the footer.
  • Reduced stack depth by not recomputing findCanonicalLibraryFor. (#1381)
  • Workaround for (#1367) forces on enableAssertInitializer.
  • Work around analyzer-0.29 bug where embedded SDK uri's aren't properly reversed.

0.10.0 #

  • fix canonicalization problems and related issues introduced or not addressed in 0.9.11, including:
    • (#1361), (#1232), (#1239 (partial))- Broken links in enums
    • (#1345) and (#1090)- Reexports have wrong links in many places
    • (#1341), (#1197 (partial)) - Duplicate docs still in some cases
    • (#1334) - Some classes don't list their subclasses
    • Inheritable class members had incorrect canonicalization in many cases
    • ... and many other unfiled bugs relating to inheritance and duplicate files.
  • Dartdoc no longer creates documentation for a given identifier more than once. This means dartdoc is 20-30% faster on complex packages.
  • --auto-include-dependencies is now recursive past one layer (#589) It now drills all the way down and will dive into the SDK and other packages.
  • Change display of warnings to be more consistent; warnings now always go to stderr and are printed on their own line.
  • Dartdoc now warns when it is unable to find a canonical object to link to
  • Dartdoc now warns if a package exports an identifier so that it is ambiguous which one should be treated as canonical
  • Dartdoc now has a number of asserts in checked mode for issues solved and as-yet-unsolved, including (#1367) or canonicalization problems; try running in checked mode if you see structural problems in generated docs and see if an assert fires.
  • Dartdoc internals have changed significantly:
    • Package now owns the calculation of recursive dependencies with a factory constructor, Package.withAutoincludedDependencies.
    • ModelElements and Libraries now have Package-scoped caches.
    • ModelElements and their subclasses now must be constructed from a single factory, ModelElements.from
    • Package has new methods to assist canonicalization, including findCanonicalLibraryFor and findCanonicalModelElementFor.
    • New mixin "Inheritable" helps class members calculate canonicalization for inheritable members
  • change order of library, class, and enum members on displayed pages (#1323).
  • change order of categories when using --use-categories, prioritizing this package first, the SDK second, packages with this package's name embedded third, and finally all other packages. A new flag, --category-order, lets you change what order categories appear in. (#1323)
  • fix broken masthead links in enums (#1225).

0.9.14-dev #

This is a prerelease only, features listed as added here don't carry forward.

  • Enable support for generic function types (#1321)

0.9.13 #

  • fix grind check-links and check-sdk-links (#1360)
  • fix multiple issues in annotation/feature list handling (#1268, #1162, #1081)
  • Added pretty-index-json command line flag.
  • index.json file entries are now sorted.

0.9.12 #

  • add print styles
  • fix for resolving references in comments (#1328)

0.9.11 #

  • add annotations to features line for methods, properties, constants (#1265)
  • fixed an issue where the search box wasn't selecting the correct result (#1330)

0.9.10 #

  • de-emphasize and resort the inherited members (#641)
  • fix bug with showing parameterized typdefs in return types of properties (#1263)
  • add macros support, to help reuse documentation (#1264)
  • de-emphasize reexported symbols in generated docs (#1158)
  • fix for angular2 docs generation (#1315)
  • generate warnings for generics not in [] in the documentation (#1250)
  • Add support for stripping schema from display text for urls defined with brackets (#1147)

0.9.9 #

  • resolve non-imported symbols in comments (#1153) - thanks @astashov!
  • support @example insertion of .md file fragments (#1105) - thanks @chalin!
  • go to the first suggestion in the search field on enter (#1149)
  • rank parent class method higher than its overrides in search suggestions (#896)
  • fix double props when inherited from parameterized class (#1228)
  • add showing docs of overridden accessors (#1266)

0.9.8+1 #

  • change the --include-external flag to help disambiguate files to include (#1236)

0.9.8 #

  • support for generic methods.
  • remove deps on cli_utils and which.
  • removed some uses of deprecated analyzer APIs

0.9.7+6 #

  • fixed an issue with generating docs with crossdart links.

0.9.7+5 #

  • update Markdown dependency to 0.11.1.

0.9.7+4 #

  • fixed an issue with documenting libraries starting with packages
  • upgraded our dependency on html to 0.13.0
  • upgraded our dependency on package_config and markdown

0.9.7+3 #

  • Extended package_config dependency to include stable 1.0.0 api.

0.9.7+2 #

  • fixed a regression with generating package docs (#1233)

0.9.7+1 #

  • change how we truncate long constant values on the summary page
  • show the full docs for enums on the summary page; just show the first line of docs for other constants

0.9.7 #

  • fix the display of long constants
  • fixed an issue with duplicate libraries in SDK
  • show source code for more element types
  • fix for issue with references in parameters and return type pointing to wrong element with same name
  • updated to a new verion of the markdown library
  • fix signatures for functions with typedef params (#1137)
  • make dartdoc strong-mode clean (#1205)
  • fix an issue w/ references in dartdoc not being hyperlinked
  • show 'abstract' for methods that are abstract
  • show the full value of enums
  • cleanup bin/dartdoc to use public dartdoc API (#1199)
  • add contribution instructions

0.9.6+2 #

  • [bug] fix an issue involving escaping constants (#1084).
  • [health] removed a dev dependency
  • [health] removed check for dartfmt on travis

0.9.6+1 #

  • [health] remove an unneeded package dependency
  • [enhancement] show the full documentation summary text for elements

0.9.6 #

  • [bug] fix enum indexes (#1176).
  • [enhancement] added support for crossdart. If there is a crossdart.json file in the input dir (which can be generated by Crossdart), it will use that file to add links to crossdart.info in the source code block.

0.9.5 #

  • [enhancement] support for @example tag to inject sample code into comments. eg. {@example core/ts/bootstrap/bootstrap.dart region='bootstrap'}, where path is path to source in the package examples directory, and region is specified by #docregion and #enddocregion in the file.
  • [enhancement] do not document if there is a @nodoc in the doc comment. NOTE: <nodoc> is now deprecated and will be removed in a later version.

0.9.4 #

  • [enhancement] added a --favicon option to specify a favicon to use for the generated docs
  • [enhancement] added a --use-categories flag to groups libraries into source packages in the overview page and the left-hand side navigation panel

0.9.3+1 #

  • [bug] fix an issue with including duplicated libraries

0.9.3 #

  • [enhancement] added support for URL-based search. If a query parameter named "search" is passed, the page navigates to the first search result for its value.
  • [enhancement] added support for passing more than one --header or --footer
  • [enhancement] added the ability to include libraries referenced by (but not directly inside) the project (--include-external)
  • [bug] rev the analyzer version used to fix an issue generating docs for Flutter

0.9.2 #

  • [bug] do not generate docs for dart:_internal and dart:nativewrappers, when defined in the _embedder.yaml file.
  • [enhancement] print message to run pub if dartdoc does not find any libraries to document.

0.9.1 #

  • [bug] fix generating docs for packages with _embedder.yaml

0.9.0 #

  • BREAKING works with Dart SDK 1.14.0 and above
  • [health] use package resource
  • [enhancement] add support for packages with _embedder.yaml
  • [bug] fix generating docs when input == '.'
  • [bug] modify showing constants so that there is no double const shown in value.

0.8.5 #

  • [enhancement] do not document if there is a <nodoc> in the doc comment.
  • [bug]link typdefs when used as parameters
  • [bug] fix issue with processing <pre> tags
  • [health] run tests only once on travis
  • [health] speed up dartdoc with caching and upgrade to latest analyzer package

0.8.4 #

  • [enhancement] Only include generator metadata in the package index.html file.
  • [bug] Fixed the display of deprecated properties.
  • [bug] show generics for typedefs
  • [bug] cleanly unzip docs on Mac
  • [health] upgrade to latest analyzer package

0.8.3 #

  • [enhancement] Added --[no-]include-source option.
  • [enhancement] Dimmed inherited members in the right sidebar.

0.8.2 #

  • [bug] fix exception due to change in analyzer, function types in parameters are no longer treated as typedefs.

0.8.1 #

  • [bug] No longer includes <base> element in the package root.
  • [bug] Eliminates a number of empty class attributes.
  • [bug] Show deprecated libraries the same way in both package and library view.
  • [bug] Process readme.md Markdown with the process that is used in document comments.

0.8.0 #

  • [bug] fix annotation shown as raw HTML in constructors
  • [bug] fix missing return type when Future
  • [enhancement] do not show "Not documented." message for members without doc comments
  • [enhancement] show constructors before properties in right side bar
  • [enhancement] sort names with embedded integers lexicographically
  • BREAKING initGenerators is now async. It returns Future<List<Generator>>.
  • BREAKING markdown_processor.dart and resource_loader.dart are no longer exposed as public libraries. Use of these libraries by third-party code is no longer supported.
  • BREAKING generator.dart is no longer exposed as a stand-alone library. You can access the Generator class by importing dartdoc.dart.

0.7.4 #

  • [bug] In class documentation, move constructors before instance properties
  • [bug] fix property pages to show documentation if not a setter/getter
  • [bug] show indented code blocks in comments as code

0.7.3 #

  • [bug] Add missing close span in accessor setter template
  • [enhancement] Print usage if an invalid argument is provided
  • [enhancement] Improve the output of asynchronous stack traces when an unhandled exception is thrown
  • [health] removed doc uploads to firebase
  • [bug] fixed incorrect 'link to Crossdart' links
  • [health] upgraded packages, modified pubspec.lock

0.7.2 #

  • [bug] do not show '///' in doc output

0.7.1 #

  • [enhancement] restore the method signature at the top of method/ctor/function/operator pages
  • [enhancement] search using fully qualified names
  • [enhancement] better messaging when library itself lacks comments
  • [enhancement] indicate when a class is an abstract class
  • [enhancement] indicate when a constructor is a factory constructor

0.7.0 #

  • [feature] --add-crossdart flag to add links to http://crossdart.info in the source code section
  • [bug] show type information for Map with generics
  • [bug] show methods/properties inherited from Object
  • [health] remove --url-mappings option, the analyzer picks up SDK extensions from the package
  • [style] changed how we display constant values

0.6.6 #

  • [style] reduce number of fonts and styles used on a page
  • [enhancement] do not show method signature for methods with source

0.6.5 #

  • [new] --rel-canonical-prefix to help with SEO for many versions of the same docs
  • [bug] fixed linking in the SDK docs
  • [enhancement] do not display comments with actual source code
  • [enhancement] show source code for constructors
  • [style] tweaks to the footer
  • [health] re-enable uploading dartdoc docs to firebase

0.6.4 #

  • [upgrade] markdown ^0.8.0
  • [health] clean up markdown files
  • [enhancement] change callable metadata to be the same as class
  • [enhancement] print annotations on separate lines

0.6.3 #

  • [bug] remove duplicate property entries
  • [enhancement] better distinction between getters and setters for properties
  • [enhancement] link inherited elements to superclass pages if available
  • [bug] fix README.md not rendering correctly on pub.dartlang
  • [health] resume testing on stable channel

0.6.2 #

  • Instructions on contributing moved to CONTRIBUTOR.md
  • Fixed bug with doc comment with name in both current and imported library might be incorrectly linked
  • Now linking to detail pages for inherited methods, operators, properties
  • Strike-through deprecated names more often (e.g. on the sidebar)

0.6.1 #

  • Removed the --package-root option. Dartdoc now uses the --input flag as the place to start looking for an analysis root. This better supports the .packages file and use cases where dartdoc is invoked from locations other than the project directory.
  • Search box displays message when it fails to load its index
  • Changed message printed when dartdoc finishes, pointing to path instead of URI
  • Reduced color saturation in header and links
  • Improved display of getters and setters on property pages

0.6.0+1 #

  • [bug] fix for getting URI for sources in lib folder

0.6.0 #

  • [enhancement] / key activates the search bar
  • [bug] combined getter/setter docs were mangled
  • [enhancement] exact matches in search now rank higher
  • [enhancement] search box starts with "Loading..."
  • [enhancement] provide a hint that there are more docs than the one-liner
  • [sdk] bundle dartdoc with SDK
  • [bug] links in right column of MapBase did not work
  • [enhancement] reorder details about a class, like inheritance
  • [sdk] fix links in SDK's front page README

0.5.0+3 #

  • [bug] fixed issue with duplicate docs for properties

0.5.0+1 #

  • [bug] fixed an issue running dartdoc as a pub global activated snapshot

0.5.0 #

  • [health] remove calls to deprecated methods
  • [health] remove workaround when sorting empty iterable
  • [sdk] now requires Dart SDK 1.12-dev or greater
  • [bug] homepage column widths now add up to 12
  • [enhancement] display ellipse when text overflows out the one-liners
  • [enhancement] section titles are larger, lighter
  • [health] testing on Windows + 1.12-dev SDK
  • [enhancement] property types are now on the right
  • [enhancement] other various style tweaks
  • [enhancement] main text is darker, links are more contrasty
  • [enhancement] include dartdoc version in generated docs, as HTML comment
  • [enhancement] remove empty-doc warnings for unnamed libraries
  • [enhancement] dartdoc understands "sdk extensions"
  • [enhancement] find-as-you-type search
  • [bug] doc references to names with multiple underscores now link correctly

0.4.0 #

  • Print the name of the thing above the right nav list
  • Numerous fixes, tests, and cleanups to the code
  • fix: top-level consts are linked correctly from doc references
  • fix: if a doc comment cannot be resolved, it is wrapped in a code element
  • fix: links generated on the Enum page
  • fix: background is dark when left drawer is open
  • fix: better error message when running dartdoc on empty directory
  • fix: don't show left drawer toggle on homescreen
  • fix: docs for a class that extends List showed double methods

0.3.0 #

  • new: left nav now animates in on mobile
  • new: white list certain libraries from the command line
  • fix: syntax highlighting of inline code
  • fix: exceptions and errors are not includes in the list of classes

0.2.2 #

  • new: show the source code for methods, functions, and constructors
  • fix: fixed an npe when generating docs for projects without readmes

0.2.1 #

  • fix: documentation for fields was sometimes null

0.2.0 #

  • fix: inconsistent heights in masthead
  • new: alphabetize lists of names
  • fix: fields w/ getters and setters were not displaying docs

0.1.0+5 #

  • show peers in left navigation bar
  • show inherited on a separate line
  • fix links to anchors
  • fix comments for properties

0.1.0+4 #

  • display only named constructor in left nav
  • do not show duplicates in implementors
  • add dart identity to page
  • left nav links to dedicated page for element

0.1.0+3 #

  • added top navigation bar
  • add left navigation section
  • package page lists libraries in left nav
  • bump version of grinder

0.1.0+2 #

  • bump version of pub_cache

0.1.0+1 #

  • remove unused dependencies (http and intl)

0.1.0 #

  • display a left-hand nav for classes and libraries
  • constants now display types in classes and libraries
  • types for properties now show on the left
  • files that act as indexes now use dash instead of underscores in their names
  • display tabs for major in-page sections

0.0.3 #

  • tweaks to margins, fonts and header
  • mobile ui improvements
  • support user defined library mapping using --url-mapping option
  • warning if library is undocumented
  • fixed linking for parameters

0.0.2+3 #

  • do not drop brackets in comments
  • replace ':' in library names with '-'
  • support multiple anonymous libraries
  • show generic information for classes
  • signature of method on same line as name
  • error if command line argument is not recognized
  • fixed href for property accesssor
  • fixed generation of docs for exported libraries

0.0.2+2 #

  • add a --package-root option
  • resource handler support for package root

0.0.2+1 #

  • handle packages that don't have a readme
  • fixed linking to references from other libraries in comments
  • resolve [new Constructor] in comments
  • link to exported library in comment references
  • visually show library is deprecated
  • fixed one liner documentation

0.0.2 #

  • documenation generated in doc/api directory
  • support for readme files in plain text
  • fixed resolving references in library comments
  • generate docs even when output directory exists
  • show inherited operators
  • visually indicate deprecated api


dartdoc examples #

Dartdoc is typically used as a command line utility to support generating documentation served on websites. In the future this directory may contain direct examples, but for now, here are pointers to the main users of dartdoc in the Dart ecosystem.

Dart SDK #

The Dart team builds docs for the Dart API reference with each new version of the SDK, via this script. Look for BuildDartdocAPIDocs.

Flutter #

The Flutter team builds API documentation for the Flutter SDK automatically. A shell script wraps a small dart program that manages the process.

pub #

The pub package website automatically builds Dart API documentation for uploaded packages.

Note, unlike the other two examples, here dartdoc is used as a library. While we make some effort not to regularly break simple uses of the library interface, we strongly recommend you use the command line and focus our semantic versioning around that case. However, if that doesn't work for your case, the pub site usage may be of interest. See this script for the entry point.

Use this package as an executable

1. Install it

You can install the package from the command line:

$ pub global activate dartdoc

2. Use it

The package has the following executables:

$ dartdoc

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  dartdoc: ^0.30.3

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:dartdoc/dartdoc.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Apr 3, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6

Health suggestions

Fix lib/src/model/package_builder.dart. (-1 points)

Analysis of lib/src/model/package_builder.dart reported 2 hints:

line 31 col 1: 'package:package_config/discovery.dart' is deprecated and shouldn't be used. Use the package_config.json based API.

line 152 col 15: 'enabledExperiments' is deprecated and shouldn't be used.

Fix lib/src/model/model_element.dart. (-0.50 points)

Analysis of lib/src/model/model_element.dart reported 1 hint:

line 840 col 15: 'getAncestor' is deprecated and shouldn't be used. Use either thisOrAncestorMatching or thisOrAncestorOfType.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.6.0 <3.0.0
analyzer ^0.39.4 0.39.5
args >=1.5.0 <2.0.0 1.6.0
collection ^1.2.0 1.14.12
crypto ^2.0.6 2.1.4
html >=0.12.1 <0.15.0 0.14.0+3
http_parser >=3.0.3 <4.0.0 3.1.4
logging ^0.11.3+1 0.11.4
markdown ^2.1.1 2.1.3
mustache ^1.1.0 1.1.1
package_config >=0.1.5 <2.0.0 1.9.3
path ^1.3.0 1.6.4
process ^3.0.5 3.0.12
pub_semver ^1.3.7 1.4.4
quiver ^2.0.0 2.1.3
resource ^2.1.2 2.1.6
stack_trace ^1.4.2 1.9.3
yaml ^2.1.0 2.2.0
Transitive dependencies
_fe_analyzer_shared 2.0.0
charcode 1.1.3
convert 2.1.1
csslib 0.16.1
file 5.1.0
intl 0.16.1
js 0.6.1+1
matcher 0.12.6
node_interop 1.0.3
node_io 1.0.1+2
platform 2.2.1
source_span 1.7.0
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
watcher 0.9.7+14
Dev dependencies
async >=2.0.8 2.4.1
build ^1.0.1
build_runner ^1.0.0
build_version ^2.0.0
coverage ^0.13.0
dhttpd ^3.0.0
glob ^1.1.5 1.2.0
grinder ^0.8.2
http ^0.12.0
io ^0.3.0
meta ^1.0.0 1.1.8
pedantic ^1.8.0 1.9.0
test ^1.3.0