跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

dartdoc-conventions

Enforces Effective-Dart documentation on the public surface — a `///` doc on every public class/method/getter/field/typedef, a one-sentence standalone summary that says WHY plus units/ranges/nullability/throws/side-effects (never a restatement of the name), verb-phrase method docs, "Whether…" boolean getters, `[bracket]` cross-links, one `library;` doc per exported barrel, in-body `//` that explains why not what, and the enforced invariant restated at its enforcement point — backed by `public_member_api_docs` and `dangling_library_doc_comments` as analyzer errors. Use when adding or reviewing a public API, a Notifier/provider, a Service interface, a sealed Failure, a value type, or preparing a package's dartdoc.

zakariaf · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add zakariaf/Flutter-Skills --skill dartdoc-conventions

技能说明


name: dartdoc-conventions description: Enforces Effective-Dart documentation on the public surface — a /// doc on every public class/method/getter/field/typedef, a one-sentence standalone summary that says WHY plus units/ranges/nullability/throws/side-effects (never a restatement of the name), verb-phrase method docs, "Whether…" boolean getters, [bracket] cross-links, one library; doc per exported barrel, in-body // that explains why not what, and the enforced invariant restated at its enforcement point — backed by public_member_api_docs and dangling_library_doc_comments as analyzer errors. Use when adding or reviewing a public API, a Notifier/provider, a Service interface, a sealed Failure, a value type, or preparing a package's dartdoc.

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 c

阅读完整来源 ↗