Dart Documentation Comment

Documentation comments in Dart are specialized comments parsed by the dart doc tool to generate structured HTML API reference documentation. Unlike standard comments, which are ignored by the documentation compiler, documentation comments are lexically bound to the declaration that immediately follows them and natively support Markdown formatting.

Syntax

Dart supports two syntaxes for documentation comments: single-line (///) and multi-line (/** ... */). The Dart style guide strongly mandates the use of consecutive single-line /// comments over the block syntax for all API documentation.

/// This is the idiomatic Dart documentation comment syntax.
/// Each line begins with three forward slashes.
String? idiomaticDoc;

/**
 * This is the legacy block documentation comment syntax.
 * It is supported by the compiler but discouraged by the linter.
 */
String? legacyDoc;

// This is a standard comment. It is ignored by the dart doc compiler.
String? undocumented;

Parsing Rules and Structure

The dart doc compiler parses the text within documentation comments using specific structural rules:

Summary Sentence: The compiler parses the first sentence of a documentation comment (up to the first period followed by whitespace) as the concise summary. This summary is extracted and displayed in high-level lists and tables within the generated documentation.
Detailed Description: Any text following the summary sentence is parsed as the detailed description, appearing only on the specific page for that member.
Markdown Processing: The compiler processes standard Markdown elements, including bolding (**text**), italics (*text*), lists, and code blocks.

/// Authenticates the user against the primary identity provider.
///
/// This method initiates a network request. If the network is unavailable,
/// it will retry up to 3 times before failing.
///
/// Required parameters:
/// * [username] The user's registered email address.
/// * [password] The plaintext password.
///
/// ```dart
/// final auth = Authenticator();
/// await auth.login('user@example.com', 'superSecret');
/// ```
Future<void> login(String username, String password) async { /* ... */ }

Lexical Linking

Dart documentation comments feature a specialized bracket syntax [identifier] to create hyperlinked references to other in-scope API elements. When the compiler encounters brackets, it attempts to resolve the enclosed text against the lexical scope of the documented element. It can resolve:

Parameters of the current method/function.
Methods, properties, and constructors of the current class.
Top-level functions, classes, and variables in the current library or imported libraries.

/// Updates the [status] of the [Transaction].
///
/// If [status] is [TransactionStatus.failed], this triggers [rollback].
void updateStatus(TransactionStatus status) { /* ... */ }

To link to a specific constructor or member of a class, the dot notation is used within the brackets: [ClassName.constructorName] or [ClassName.methodName].

Directives and Pragmas

The documentation compiler recognizes specific directives (often prefixed with @) embedded within the comments to control documentation generation:

@nodoc: Instructs the compiler to exclude the associated member (and its children, if it is a class) from the generated HTML output, even if it is public.
@template / @macro: Used for documentation reuse. @template template_name defines a block of documentation, and {@macro template_name} injects that block into another documentation comment, preventing duplication across similar API members.

/// {@template base_http_exception}
/// Thrown when an HTTP request fails at the transport layer.
/// {@endtemplate}
class HttpException implements Exception {}

/// {@macro base_http_exception}
///
/// Specifically indicates a 404 Not Found response.
class NotFoundException extends HttpException {}