Writing Dart API Documentation

Contents

• 1. Scope and Structure
• 2. Tone and Openers
• 3. Strict Anti-Patterns (Banned)
• 4. Technical Placement & Resolution
• 5. Linking and Markdown
• 6. Verification
• Examples

When asked to write or update documentation for Dart code, you must strictly follow these formatting rules based on the "Effective Dart: Documentation" guidelines.

1. Scope and Structure

• Target Public APIs: Focus your documentation efforts on public declarations. Do not document private members (those starting with an underscore _) unless explicitly instructed, as they do not appear in generated API reference sites.
• Always use ///: Use /// consecutive line comments for all API documentation. Never use /** ... */ block comments.
• Proper Sentences: Format all comments like proper sentences. Capitalize the first word (unless it's a lowercase identifier) and end with a period.
• The First Paragraph: The first paragraph of a doc comment must be a single, concise sentence that summarizes the element. End it with a period. Dartdoc extracts this verbatim for list views.
• Separation: Always separate the first sentence summary from the rest of the documentation with a blank line containing ///. Never output a completely empty newline (e.g., a \n without ///), as this terminates the doc comment block.