dart-write-documentation

SKILL.md

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.