Doc comments

Domains: Dart

Doc comments are especially handy because https://github.com/dart-lang/dartdoc" target="_blank">dartdoc parses them and generates beautiful doc pages from them. A doc comment is any comment that appears before a declaration and uses the special /// syntax that dartdoc looks for.

DO

DO use /// doc comments to document members and types

Using a doc comment instead of a regular comment enables dartdoc to find it and generate documentation for it.

/// The number of characters in this chunk when unsplit. 
int get length => ...

For historical reasons, dartdoc supports two syntaxes of doc comments: /// (“C# style”) and /** ... */ (“JavaDoc style”). We prefer /// because it’s more compact. /** and */ add two content-free lines to a multiline doc comment. The /// syntax is also easier to read in some situations, such as when a doc comment contains a bulleted list that uses * to mark list items.

If you stumble onto code that still uses the JavaDoc style, consider cleaning it up.

DO start doc comments with a single-sentence summary

Start your doc comment with a brief, user-centric description ending with a period. A sentence fragment is often sufficient. Provide just enough context for the reader to orient themselves and decide if they should keep reading or look elsewhere for the solution to their problem.

/// Deletes the file at [path] from the file system. 
void delete(String path) { 
   ... 
}

DO separate the first sentence of a doc comment into its own paragraph

Add a blank line after the first sentence to split it out into its own paragraph. If more than a single sentence of explanation is useful, put the rest in later paragraphs. This helps you write a tight first sentence that summarizes the documentation. Also, tools like Dartdoc use the first paragraph as a short summary in places like lists of classes and members.

/// Deletes the file at [path]. 
/// 
/// Throws an [IOError] if the file could not be found. Throws a 
/// [PermissionError] if the file is present but could not be deleted. 

void delete(String path) { 
   ... 
}

DO use square brackets in doc comments to refer to in-scope identifiers

If you surround things like variable, method, or type names in square brackets, then dartdoc looks up the name and links to the relevant API docs. Parentheses are optional, but can make it clearer when you’re referring to a method or constructor.

/// Throws a [StateError] if ... 
/// similar to [anotherMethod()], but ...

To link to a member of a specific class, use the class name and member name, separated by a dot:

/// Similar to [Duration.inDays], but handles fractional days.

The dot syntax can also be used to refer to named constructors. For the unnamed constructor, put parentheses after the class name:

/// To create a point, call [Point()] or use [Point.polar()] to ...

DO use prose to explain parameters, return values, and exceptions

Other languages use verbose tags and sections to describe what the parameters and returns of a method are.

The convention in Dart is to integrate that into the description of the method and highlight parameters using square brackets.

/// Defines a flag. 
/// 
/// Throws an [ArgumentError] if there is already an option named [name] or 
/// there is already an option using abbreviation [abbr]. Returns the new flag. 
Flag addFlag(String name, String abbr) => ...

DO put doc comments before metadata annotations

/// A button that can be flipped on and off. 
@Component(selector: 'toggle') 
class ToggleComponent {}

PREFER

PREFER writing doc comments for public APIs

You don’t have to document every single library, top-level variable, type, and member, but you should document most of them.

PREFER starting function or method comments with third-person verbs

The doc comment should focus on what the code does.

/// Returns `true` if every element satisfies the [predicate]. 
bool all(bool predicate(T element)) => ... 

/// Starts the stopwatch if not already running. 
void start() { 
   ... 
}

PREFER starting variable, getter, or setter comments with noun phrases

The doc comment should stress what the property is. This is true even for getters which may do calculation or other work. What the caller cares about is the result of that work, not the work itself.

/// The current day of the week, where `0` is Sunday. 
int weekday; 

/// The number of checked buttons on the page. 
int get checkedCount => ...

Avoid having a doc comment on both the setter and the getter, as DartDoc will show only one (the one on the getter.)

PREFER starting library or type comments with noun phrases.

Doc comments for classes are often the most important documentation in your program. They describe the type’s invariants, establish the terminology it uses, and provide context to the other doc comments for the class’s members. A little extra effort here can make all of the other members simpler to document.

/// A chunk of non-breaking output text terminated by a hard or soft newline. 
/// 
/// ... 
class Chunk { ... }

CONSIDER

CONSIDER writing a library-level doc comment

Unlike languages like Java where the class is the only unit of program organization, in Dart, a library is itself an entity that users work with directly, import, and think about. That makes the library directive a great place for documentation that introduces the reader to the main concepts and functionality provided within. Consider including:

  • A single-sentence summary of what the library is for.
  • Explanations of terminology used throughout the library.
  • A couple of complete code samples that walk through using the API.
  • Links to the most important or most commonly used classes and functions.
  • Links to external references on the domain the library is concerned with.

You document a library by placing a doc comment right above the library directive at the start of the file. If the library doesn’t have a library directive, you can add one just to hang the doc comment off of it.

CONSIDER writing doc comments for private APIs

Doc comments aren’t just for external consumers of your library’s public API. They can also be helpful for understanding private members that are called from other parts of the library.

CONSIDER including code samples in doc comments

/// Returns the lesser of two numbers. 
/// 
/// ```dart 
/// min(5, 3) == 3 
/// ``` 
num min(num a, num b) => ...

Humans are great at generalizing from examples, so even a single code sample makes an API easier to learn.

AVOID

AVOID redundancy with the surrounding context

The reader of a class’s doc comment can clearly see the name of the class, what interfaces it implements, etc. When reading docs for a member, the signature is right there, and the enclosing class is obvious. None of that needs to be spelled out in the doc comment. Instead, focus on explaining what the reader doesn’t already know.

class RadioButtonWidget extends Widget { 
   /// Sets the tooltip to [lines], which should have been word wrapped using 
   /// the current font. 

   void tooltip(List<String> lines) { 
      ... 
   } 
}

Similar pages

Page structure
Terms

String

Methods

Dart

List

Parameters

Classes

int

Functions

Constructor

Getters and setters

Types

Numbers

bool

Return values

Named constructor