Dart: Documenting Your Code

1. dart
2. fundamentals

Documenting your code is essential for creating clean, readable and robust applications. Imagine trying to utilise a 3rd party library without documentation! You would have to reverse-engineer the code just to get it to work.

A bundled tool named dartdoc collects all these document comments and can generate doc pages from them.

💡 Note
You don't have to document every single API in your code, but it is good practice to have documentation for public APIs.

Example

The syntax for documenting Dart code is incredibly lightweight. You do not need to mark each section using XML (as in C#).

Lets take a look at the LocalKey class directly from key.dart in the Flutter source code:

/// A key that is not a [GlobalKey].
///
/// Keys must be unique amongst the [Element]s with the same parent. By
/// contrast, [GlobalKey]s must be unique across the entire app.
///
/// See also:
///
///  * [Widget.key], which discusses how widgets use keys.
abstract class LocalKey extends Key {
  /// Default constructor, used by subclasses.
  const LocalKey() : super.empty();
}

Lets step through it piece by piece in order to fully understand what it all means.

Slashes

Lines starting with /// are doc comments and are picked up by dartdoc. These are placed before the declaration of functions, types, classes etc. These differ from regular // comments in code, which may be added to clarify the original developer's intent.

Summary

/// A key that is not a [GlobalKey].

This first line is a summary of the class, giving you an idea of what it does before moving on to a longer description. Having a concise summary first allows developers to skim documentation or source code and get a rough idea of how to work with it, choosing to read further if necessary.

Description

///
/// Keys must be unique amongst the [Element]s with the same parent. By
/// contrast, [GlobalKey]s must be unique across the entire app
///

A longer description is supplied after the summary. This goes into further detail, perhaps describing class invariants or function parameters, exceptions that may be thrown and so on.

Notice the blank lines? These just provide spacing for the distinct parts of the doc comment and make it easier to read.

Linking to in-scope members

/// amongst the [Element]s with the same parent...

See those square brackets surrounding Element? They provide a way for dartdoc to look up the name inside and link through to the appropriate API docs. In this case [Element] will take you to the docs for the main Element class.

You don't have to, but adding perenthesis helps to identify that you are referring to a method or function:

/// Calling [execute()] on this [CommandHandler] will execute the handler
/// using the supplied command. This method is deliberately bare, as all
/// information required should be encapsulated in the [Command].

Extras

/// See also:
///
///  * [Widget.key], which discusses how widgets use keys.

This portion just adds some further information to read if you need to, but the interesting addition here is the use of markdown syntax * to denote an unordered list with an item.

Hold on, we can use Markdown?

Absolutely! Due to Markdown's immense popularity, dartdoc supports the use of markdown syntax within doc comments:

/// Some regular text first
///
/// Let's add a list:
///
/// - An unordered
/// - List of items
///
/// You **should** use markdown syntax for your comments, other
/// developers will _really_ love being able to read clean,
/// well-written notes.
///
/// Here's [an article](https://www.oreilly.com/content/the-eight-rules-of-good-documentation/)
/// about writing good documentation.

This gives you very powerful syntax for formatting your documentation.

Generating documentation

You can generate documentation for your project using the dartdoc command.

dartdoc
Documenting super_duper_app...
...
Success! Docs generated into /Users/adam/Projects/super_secret_app/doc/api

After the process has finished, the can be found in <project>/doc/api.

---

What are you waiting for? Get documenting!