dart-write-documentation

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.

2. Tone and Openers

• Noun phrases for properties: Start descriptions of variables, getters, or setters with a noun phrase. /// The radius of the sphere. (Not "Gets the radius...")
• "Whether" for booleans: Start documentation for boolean properties with "Whether". /// Whether the connection is active.
• Third-person verbs for methods: Start descriptions of methods or functions with a third-person verb that describes what it does. /// Initializes the database. (Not "Initialize" or "This method initializes").
• Avoid redundancy: Do not restate the signature or the element name. Do not say "This class is a..." or "The foo method does...".