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
- Every public declaration gets a
///doc — public classes, constructors, methods, getters, top-level functions, typedefs, and fields.public_member_api_docsis 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. ///, never/** */. Dartdoc only recognizes///. A JavaDoc block is silently ignored and the symbol reads as undocumented.slash_for_doc_commentsflags it.- 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. - Method/function docs start with a verb phrase (third person): "Returns…", "Schedules…", "Loads…", "Marks…". A boolean getter or
bool-returning method starts with "Whether…". - Never restate the name.
/// The name.onString name,/// Returns the total.ontotal()— 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. - Cross-link identifiers in
[brackets]so dartdoc resolves them:/// Throws [StateError] if [id] is unknown; see [copyWith].comment_referenceswarns on a broken link. - 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. - 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. - 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.
- One library doc per exported barrel. The public entry point (e.g.
my_package.dart) gets a///library doc above thelibrary;directive.dangling_library_doc_commentsis an error — a leading///with no attached declaration must be a real library doc, not an orphan above a blank line or anexport.
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
阅读完整来源 ↗