Guidelines for Dart Doc Comments

Written by Kathy Walrath

This document describes the conventions the Dart team has agreed upon for documentation comments. If you have suggestions for improving the conventions, let us know.

Contents

  1. Examples
  2. Content
    1. First paragraph: a “one-sentence” description
    2. The rest of the doc comment
  3. Markup
    1. Links
    2. Block styles
    3. Inline styles
  4. Word choice, punctuation, and so on
  5. Resources

Examples

Here’s a typical comment for a function or method:

/**
 * Returns the lesser of two numbers.
 *
 * Returns NaN if either argument is NaN.
 * The lesser of -0.0 and 0.0 is -0.0.
 * If the arguments are otherwise equal (including int and doubles with the
 * same mathematical value) then it is unspecified which of the two arguments
 * is returned.
 *
 *     return min(100, value);
 */
num min(num a, num b) {/*...*/}

And one for a variable or property:

/// The PI constant.
const double PI = 3.1415926535897932;

For an example of a class description with example code, see Completer (generated doc, source code).

Content

The first paragraph of a doc comment is special. After that, the content is up to you, although we strongly recommend including code samples.

First paragraph: a “one-sentence” description

As the examples at the top of this document show, the first paragraph of any doc comment is a brief, user-oriented description ending with a period. It is not a complete sentence.

The description should help the reader understand whether this bit of API might be useful to them, compared to similar sounding API. Never just repeat the API name; try to restate it to give more information than the name alone provides. Avoid links when possible.

Functions and methods

Function/method descriptions begin with a third-person verb.

Examples:

Variables, getters, and setters

Static/instance variable and getter/setter descriptions are noun phrases.

If there’s both a setter and a getter, comment only the getter. That way, it’ll be treated as a variable. Don’t include the type, since that’s already in the signature.

Example:

Classes

Class descriptions are noun phrases.

Examples:

The rest of the doc comment

Subsequent paragraphs explain return values, what arguments you can specify, side effects, exceptions that users might want to catch, related APIs, and so on.

Be sure to provide code examples for the most common uses of the API, and links to documents that provide more information.

Markup

Format your text using the markup specified in section 15.1.2 of the Dart Language Specification. Although dartdoc currently recognizes some additional markdown (as noted below), it might not always.

When in doubt, format less. You’ll be less likely to break the docs, and someone else can always add formatting.

You can link to Dart identifiers, of which constructors are a special case, or to any URI you choose.

Identifier

[id] or [id](uri)

If id is the name of a class, the generated link points at the class, even if the class has a constructor of the same name. If you specify uri, it must be the URI of a dart library L, and id must a name declared in the exported namespace of L.

Constructor

[new c] or [new c](uri)

[text](uri) or <uri>

Note: uri is the URI to link to; text is the string to be displayed instead of the URI.

Block styles

Paragraph

Use a blank line to denote the end of a paragraph.

Code block

Use four blank spaces after the line’s comment characters, which means five spaces after the * or / (since they’re always followed by a space). Example:

/**
 * ...
 * For example:
 *
 *     Future&lt;int> future = getFutureFromSomewhere();
 *     future.then((value) {
 *       print("I received the number $value");
 *     });
 * ...
 */

## header text until newline

Lower level heads (such as ###) are currently implemented but not specified.

Bulleted (unordered) list item

* item continues until next list item or blank line

The line before the first bulleted list item must be blank.

Numbered (ordered) list item

1. item continues until next list item or blank line
2. next item

The specification states that items aren’t autonumbered. Use 2. for item #2, 3. for item #3, and so on.

Inline styles

Code font

`code` (note the backquotes) or [:code:]

Avoid code font unless it’s (1) a big chunk of code or (2) necessary to prevent confusion.

Italics

_single underscore_ or *single asterisk*

It’s possible that when the specification is clarified, a single asterisk will mean boldface.

Boldface

**double asterisk** or __double underscore__

The specification doesn’t include double asterisk and underscore, and it’s possible that a single asterisk will mean boldface.

Here’s an example of a warning:

/**
 * ...
 * **Warning:** This feature is not yet supported in all modern browsers.
 * See <http://caniuse.com/flexbox> for current status.
 * ...
 */

Word choice, punctuation, and so on

Resources