Agent skill · dart-lang
dart-write-documentation
Rules and formatting guidelines for writing Dart /// API documentation and doc comments. Use when documenting Dart code, writing doc comments for any Dart declaration (libraries, classes, methods, variables, etc.), or when instructed to follow the Effective Dart documentation guidelines.
What it needs
About 4k tokens when loaded.
What this skill does
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...". 3. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills dart-lang/dart-write-documentation