Documenting Dart Code

Contents

• Core Principles
• Formatting Doc Comments
• Documenting Specific Constructs
• Workflow: Generating and Validating Docs
• Examples

Core Principles

• Use /// exclusively: Document members and types using ///. Never use /** ... */ block comments for documentation.
• Use // for internal comments: Use standard // comments for implementation details that should not appear in generated public documentation.
• Format as sentences: Capitalize the first word (unless it is a case-sensitive identifier) and end with a period.
• Prefer brevity: Be clear, precise, and terse. Avoid redundant information that can be inferred from the method signature or class name.
• Use Markdown: Utilize standard Markdown for formatting. Prefer backtick fences (```) for code blocks over indentation. Avoid HTML tags.

Formatting Doc Comments

• Start with a summary: Begin the first sentence with a brief, third-person singular summary.