Documenting your app

A project needs to be documented so that future developers can change and expand it. From release 1.2 onwards, the docgen tool is provided as an API Documentation Generator, which generates and serves documentation for the Dart SDK and packages, as well as for your applications. This recipe is designed to show you how to best document the application you have built.

Getting ready

Run pub get on your project before running the docgen tool. We will illustrate this with the bank_terminal_polymer app.

How to do it...

1. In a command-line session at the top level of your app, run:

   docgen .
   

2. When the documentation is generated, issue the following command:

   docgen --serve .
   

   This installs the dartdoc-viewer tool and starts up a local web server for your docs, which you can access via the URL http://localhost:8080. The following is a screenshot from the BankAccount class documentation (you can change the view with the Options menu):

   

   Viewing documentation

How it works...

The command creates a docs folder in your app, and writes JSON files with the API information in them for your app's lib folder, as well as for every imported package and the Dart SDK. Dartdoc comments (/** … */) are included.

There's more...

To make the docs available from an intranet web server or from an Internet web server, perform the following steps:

1. Copy dartdoc-viewer (compiled to JavaScript) onto the server.
2. Copy the generated files to a docs directory under the main URL.

Also, private declarations are ignored unless the flag --include-private is used. Various other options are documented at https://www.dartlang.org/tools/docgen/#options.

A command that specifies the output folder and does not generate docs for the SDK and packages will be as follows:

docgen --out out/doc/api --no-include-sdk --no-include-dependent-package
s --compile lib/app.dart