Dartdoc: Generate a nice documentation for your Dart package

We developers love creating code. But this is not only about writing actual code but, for example, also about writing documentation for your code. Now you can say that code should be self-documenting. Which definitely should be but this is not everything.

Writing documentation for your code gives you a lot of benefits and it should be part of your daily coding job.

Documentation and Dart

There is a really nice article about writing documentation in your Dart projects and this my blog post will show you how to benefit from your documented Dart code.

Dart has a tool for generating nice HTML documentation for your Dart package. The latest Dart version - Dart 1.12 came with a new version of this tool, now called dartdoc, which replaces the old docgen tool.

Dartdoc generates a nice HTML documentation for your package easily and very fast. And it also looks really nice.

How to run dartdoc?

Simply run dartdoc tool from the root directory of your package.

dartdoc

Just that simple. No extra parameters needed.

And now watch how it generates a nice documentation into a doc folder in your project. Then just simply open the doc/api/index.html file in your web browser and tadaaa, you can explore your documentation :-) Nicely generated documentation available really fast.

For a usage information about the command add -h or --help option:

dartdoc --help
Generate HTML documentation for Dart libraries.

Usage: dartdoc [OPTIONS]

-h, --help            Show command help.
    --version         Display the version for dartdoc.
    --dart-sdk        Location of the Dart SDK. Use if SDK isn't automatically located.
    --sdk-docs        Generate ONLY the docs for the Dart SDK.
    --sdk-readme      Path to the SDK description file. Use if generating Dart SDK docs.
    --input           Path to source directory
                      (defaults to "/Users/janamou/Projects/my_super_project")

    --output          Path to output directory.
                      (defaults to "doc/api")

    --header          path to file containing HTML text, inserted into the header of every page.
    --footer          path to file containing HTML text, inserted into the footer of every page.
    --package-root    The path to the package root.
    --url-mapping     --url-mapping=libraryUri,/path/to/library.dart directs dartdoc to use "library.dart" as the source for an import of "libraryUri"
    --exclude         Comma-separated list of library names to ignore.
    --include         Comma-separated list of library names to generate docs for.
    --hosted-url      URL where the docs will be hosted (used to generate the sitemap).

Dartdoc tool is also available on Github so if you find any issue with it, you can simply report it. Or you can contribute to the project.

Dartdoc in action

If you want to see new dartdoc already in action, take a look at the official Dart SDK API documentation. Browse through it. Nice isn't it?

Have you already tried dartdoc? Is generating of documentation part of your workflow?

Se ya soon again!