dart-write-documentationlisted

# Writing Dart API Documentation ## Contents * [1. Scope and Structure](#1-scope-and-structure) * [2. Tone and Openers](#2-tone-and-openers) * [3. Strict Anti-Patterns (Banned)](#3-strict-anti-patterns-banned) * [4. Technical Placement & Resolution](#4-technical-placement--resolution) * [5. Linking and Markdown](#5-linking-and-markdown) * [6. Verification](#6-verification) * [Examples](#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 ne