When to Use

Writing /// doc comments on classes, methods, properties, or top-level functions
Reviewing existing documentation for completeness
Generating API docs with dart doc
Enforcing documentation linting rules

Critical Rules

Rule	Description
Use `///` not `/** */`	Dart convention uses triple-slash, not block comments
First sentence is a summary	Must be a single, concise sentence ending in `.`
Start with a verb (methods)	`/// Returns`, `/// Creates`, `/// Throws`
Start with a noun (classes)	`/// A button that...`, `/// Repository for...`
Document the WHY, not the WHAT	Code shows what; docs explain why and when
No redundant docs	Don't document obvious getters/setters unless they have side effects

Related skills