Skip to main content
Documentation comments are specialized lexical tokens within Dart source code, denoted by specific delimiters, that allow the Dart compiler and the dart doc tool to extract metadata and descriptive text for API reference generation and IDE code intelligence.

​
Syntax Variants

Dart supports two syntactic forms for documentation comments. Both forms are parsed by the documentation generator and attached to the abstract syntax tree (AST) node immediately following the comment. Single-line Style (Preferred) Denoted by a triple slash ///. This style is strictly recommended by the Dart style guide for all documentation. 
/// A documentation comment for a class.
///
/// This is the second paragraph.
class MyClass {
  /// A documentation comment for a member.
  void myMethod() {}
}
Block Style Denoted by /** to open and */ to close. While syntactically valid, this style is discouraged. Note: The compiler treats /** as a documentation comment and will attach the enclosed text to the next declared symbol. To disable code without generating documentation, use the standard block comment /* ... */. 
/**
 * A block-style documentation comment.
 *
 * Asterisks on intermediate lines are optional but conventional.
 */
void legacyMethod() {}

​
Content Parsing

The content within documentation comments is parsed as CommonMark (Markdown). The parser recognizes standard Markdown elements including:
  • Code blocks: Indented by 4 spaces or fenced with triple backticks.
  • Inline code: Enclosed in single backticks.
  • Lists: Ordered and unordered.
  • Headers: Denoted by hash symbols (#).
Summary Extraction The first paragraph of the comment block is extracted as the summary fragment. This text extends from the beginning of the comment to the first blank line (double newline). This fragment is used in list views, package indexes, and IDE hover tooltips. 
/// This entire paragraph constitutes the summary. It may contain multiple
/// sentences. It ends only when a blank line is encountered.
///
/// This is the detailed description, which is not included in the summary.
void method() {}

​
Symbol Reference Resolution

Dart documentation comments support in-scope symbol linking using square brackets [...]. The documentation generator resolves these references based on the lexical scope of the documented element. 
/// Calculates the sum of [a] and [b].
///
/// See also: [Calculator.subtract] and [math.max].
int add(int a, int b) => a + b;
  • Parameters: [a] resolves to the function parameter.
  • Members: [Calculator.subtract] resolves to a specific method in a class.
  • Libraries: [math.max] resolves to an imported library member.
  • Constructors: [MyClass.new] or [MyClass.named] resolves to class constructors.

​
Directives

Documentation comments support specific inline directives enclosed in braces that alter the behavior of the documentation generator.
  • {@nodoc}: Instructs the generator to exclude the documented element from the generated output.
  • {@canonicalFor element}: Asserts that the current library is the canonical location for a specific element, overriding default location logic (e.g., {@canonicalFor MyClass}).
  • {@tool ...} / {@end-tool}: Allows the embedding of external tools or samples within the documentation.
Note: Deprecation is handled via the @Deprecated metadata annotation applied to the code declaration, not via a documentation directive.

​
Library Documentation

To attach documentation to a library itself, the documentation comment must be placed immediately before a library directive. If a documentation comment is placed at the top of a file without a library directive, the parser attaches the comment to the first import, export, or declaration it encounters, rather than the library. 
/// Utilities for string manipulation.
///
/// This text serves as the library-level documentation.
library string_utils;

import 'package:characters/characters.dart';
Master Dart with Deep Grasping Methodology!Learn More