Writing documentation for your code gives you a lot of benefits and it should be part of your daily coding job.
Documentation and DartThere 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.
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 actionIf 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!