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.

Documenting a value type

/// A note the user has authored and can later edit or archive.
///
/// Immutable; derive changes with [copyWith]. [updatedAt] is UTC and never
/// precedes [createdAt].
class Note {
  /// Creates a note; [updatedAt] must not precede [createdAt].
  const Note({
    required this.id,
    required this.title,
    required this.createdAt,
    required this.updatedAt,
  });

  /// Stable unique identifier, assigned once at creation.
  final String id;

  /// Human-readable heading shown in lists; may be empty, never null.
  final String title;

  /// Creation instant, in **UTC**.
  final DateTime createdAt;

  /// Last-edit instant, in **UTC**; equals [createdAt] until first edited.
  final DateTime updatedAt;

  /// Returns a copy with the given fields replaced.
  Note copyWith({String? title, DateTime? updatedAt}) => Note(
        id: id,
        title: title ?? this.title,
        createdAt: createdAt,
        updatedAt: updatedAt ?? this.updatedAt,
      );
}

Every public field carries a ///, including title — under the enforced public_member_api_docs a field that "restates the name" is not a licence to drop the doc but a prompt to say something real (or make the field _-private). Document units and constraints explicitly where the type does not carry them: minor currency units, a 0–23 hour, an inclusive/exclusive range, what null means, "must be > 0".

Documenting behavior — throws, async, side effects

/// Schedules a reminder for [task] at [when].
///
/// [when] must be in the future; a past instant is clamped to now. Persists the
/// scheduled row before arming the OS notification, so a crash mid-call cannot
/// leave a notification the store never recorded.
///
/// Throws [PermissionDeniedException] if the OS denied notification permission.
Future<void> scheduleReminder(Task task, DateTime when) async {
  // persist-before-arm: the store is the source of truth, the OS mirrors it
  await _store.saveScheduled(task.id, when);
  await _plugin.schedule(task.id, when);
}

State async behavior, what a method writes or mutates, and every exception it can throw. If a function is total (returns for every input, never throws), say so — it is a real guarantee callers rely on.

Library docs and the exported barrel

/// Pure-Dart domain core: value types, typed failures, and total functions.
///
/// No Flutter, Riverpod, or `dart:io` import — this purity is what lets the
/// core be unit-tested without a widget harness and reused across platforms.
library;

export 'src/note.dart';
export 'src/task.dart';

The /// attaches to the library; directive. Never leave a /// dangling above an export or a blank line.

Restating the invariant at the enforcement point

Where a symbol enforces a rule, document the rule as part of its contract and pin it in-body at the one line that upholds it:

/// Failure modes of a checkout. Switched exhaustively by the caller, so a new
/// case is a compile error at every call site.
sealed class CheckoutFailure {
  /// Const base constructor, so subclasses can be `const`.
  const CheckoutFailure();
}

/// The account balance was below the order total; no charge was made.
final class InsufficientFunds extends CheckoutFailure {
  /// Creates an [InsufficientFunds] failure.
  const InsufficientFunds();
}

/// Read-only view of the current order; mutated only through this notifier.
class OrderNotifier extends Notifier<Order> {
  @override
  Order build() => Order.empty();

  /// Adds [item] and recomputes the total.
  ///
  /// Persists via the repository before emitting, so a mid-write crash cannot
  /// surface a line the store never saw.
  Future<void> addItem(Item item) async {
    // persist-before-emit: emitted state is always a state the store holds
    await _repository.append(item);
    state = state.withItem(item);
  }
}

Anti-patterns

• /** JavaDoc-style */ — dartdoc ignores it; the symbol reads as undocumented and fails public_member_api_docs.
• Restating the name — /// Gets the id. on String get id. Delete it or add units/ranges/invariants.
• A paragraph before the one-sentence summary — the first sentence must stand alone in list views.
• Narrating mechanics in-body — // loop over items, i++ // increment. Explain why, or delete.
• A magic constant with no source — a bare 3 for a cap with no comment saying where the number is defined.
• Stale docs describing pre-refactor parameters, or an invariant comment left on code that no longer honors it.
• Commented-out code "just in case" — git remembers. // TODO with no owner or issue link — write // TODO(name): reason or nothing.
• Documenting private trivia while a public method sits undocumented.
• A dangling /// above a blank line or an export — fails dangling_library_doc_comments.
• Banner / ASCII-art comment dividers that bloat files; rely on structure and naming.

Definition of done

• Every public declaration in the touched code has a /// doc; first line is a standalone sentence ending in a period.
• Method/function docs start with a verb; boolean getters start with "Whether".
• Units, ranges, nullability, throws/Result, and side effects documented where they exist.
• Identifiers cross-linked with [brackets]; no broken comment_references.
• Enforced invariants restated at their enforcement points; magic constants cite their source.
• No restated-name docs, no narrating //, no commented-out code, no ownerless TODO, no JavaDoc blocks.
• Each exported barrel has a library; doc; no dangling doc comments.
• Every comment the diff touched is still true.
• dart analyze --fatal-infos --fatal-warnings clean; dart doc generates without warnings for packages.

Related skills

• See lint-and-style-config for wiring public_member_api_docs, dangling_library_doc_comments, and comment_references as analyzer errors.
• See naming-conventions for the role-suffix names (Notifier/Repository/Service/Failure) these docs describe.
• See dart3-idioms-and-coding-standards for the sealed-type and total-function guarantees the docs promise.
• See error-handling-typed-results for the Result/Failure contract a method doc must state.

References

• Effective Dart: Documentation
• dart doc tool
• Linter rules — public_member_api_docs, dangling_library_doc_comments, comment_references, slash_for_doc_comments
• Developing packages & plugins