dartdoc-conventions

Dartdoc Conventions — the public surface is a contract

Public code is read far more than it is written. A symbol with no leading _ is a contract callers depend on, so it carries a /// doc a reader understands without opening the body. Doc comments use /// and follow Effective Dart: Documentation. Applies whenever you add or change a public declaration, or write an in-body // comment.

Non-negotiable rules

1. Every public declaration gets a /// doc — public classes, constructors, methods, getters, top-level functions, typedefs, and fields. public_member_api_docs is an error with no "obvious member" exemption: it flags every undocumented public member, so a missing doc fails the build. Making a symbol public "just in case" is a review reject — make it _-private instead so it needs no doc and no contract.
2. ///, never /** */. Dartdoc only recognizes ///. A JavaDoc block is silently ignored and the symbol reads as undocumented. slash_for_doc_comments flags it.
3. First line is one standalone sentence ending in a period, in its own paragraph. Tools show only this sentence in API lists, so it must stand alone; a blank /// line separates it from the body.
4. Method/function docs start with a verb phrase (third person): "Returns…", "Schedules…", "Loads…", "Marks…". A boolean getter or bool-returning method starts with "Whether…".
5. Never restate the name. /// The name. on String name, /// Returns the total. on total() — banned. If a public member has nothing to add beyond its name, that is the signal to make it _-private (a private member needs no doc, so the tension disappears). A member that must stay public still needs a real /// — never leave it public-and-undocumented; add meaning: units, ranges, nullability, throws, side effects, and the invariant the symbol enforces.
6. Cross-link identifiers in [brackets] so dartdoc resolves them: /// Throws [StateError] if [id] is unknown; see [copyWith]. comment_references warns on a broken link.
7. In-body // explains why, never what. The code already says what. Narrating comments (// loop over items) rot out of sync and become misinformation. Comment the reason, the gotcha, or the invariant.
8. Restate an enforced invariant at its enforcement point. Where one line upholds a guarantee — an ordering, a clamp, a persist-before-publish, a canonical-unit conversion — a terse // states it so a diff that weakens it gets an unmissable flag. Same for a magic constant: cite where the number comes from.
9. Docs change in the same diff as the code. A wrong doc is worse than none. Every comment your change touches must still be true — put it on the PR checklist.
10. One library doc per exported barrel. The public entry point (e.g. my_package.dart) gets a /// library doc above the library; directive. dangling_library_doc_comments is an error — a leading /// with no attached declaration must be a real library doc, not an orphan above a blank line or an export.