Documentation

Dart doc comments

You make a doc comment by putting /// right before something.

// normal comment, boring
int x;

/// doc comment 😎
int y;

Anything can have a doc comment! The only exception is stuff inside a function.

/// class!
class Class {
  /// class member!
  bool value = false;

  /// class method!
  void foo() {
    // gotta have a normal comment here
    int i = 0;
  }
}

This lets you do a lot of cool things:

• link to something else using [brackets]
• use {@template} and {@macro} to reference documentation from somewhere else
• add bullet points, code snippets, and more, using Markdown syntax

You can see the documentation any time you hover your mouse on the relevant text:

And when you publish an open-source package, the doc comments are automatically published online too! (See pub.dev/documentation/provider as an example.)

Doc comment conventions

Doc comments should be written in complete sentences, and they should be useful (as per the style guide from the wiki in the Flutter source code repository).