dartdoc-conventions

Enforces Effective Dart documentation rules on public Dart APIs.

Updated Aug 22, 2026
One-click install
npx skills add https://github.com/zakariaf/NearlyStop --skill dartdoc-conventions-zakariaf
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: dartdoc-conventions
Source: https://github.com/zakariaf/NearlyStop/tree/main/.claude/skills/dartdoc-conventions
Command: npx skills add https://github.com/zakariaf/NearlyStop --skill dartdoc-conventions-zakariaf

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Public Dart APIs often ship with missing, stale, or name-restating doc comments that give callers no real contract. This Skill enforces Effective Dart documentation standards so every public declaration carries a meaningful /// doc backed by analyzer errors. ## Core Features & Use Cases - Complete public-surface coverage: Requires a /// doc on every public class, method, getter, field, and typedef, enforced by public_member_api_docs as an analyzer error. - Contract-quality content: Mandates one-sentence standalone summaries, verb-phrase method docs, "Whether…" boolean getters, [bracket] cross-links, and explicit units, ranges, nullability, throws, and side effects. - Invariant pinning: Restates enforced invariants at their enforcement point with in-body // comments that explain why, never what. - Use Case: When adding a new Riverpod Notifier or sealed Failure class to a Flutter package, apply this Skill to document every public member, wire the library barrel doc, and pass dart analyze --fatal-infos --fatal-warnings cleanly. ## Quick Start Review the public API in my Dart package and write Effective-Dart-compliant doc comments for every undocumented public declaration.

Frequently Asked Questions about dartdoc-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document public Dart APIs with dartdoc?

Write a `///` doc comment on every public class, method, getter, field, and typedef. Start with one standalone summary sentence, use verb phrases for methods, "Whether…" for boolean getters, and cross-link identifiers in [brackets].

What is the public_member_api_docs lint rule in Dart?

public_member_api_docs is an analyzer lint that flags every undocumented public member. Configured as an error, it fails the build when any public declaration lacks a `///` doc, with no exemption for seemingly obvious members.

Why does dartdoc ignore my JavaDoc-style comments?

Dartdoc only recognizes `///` line comments; `/** */` blocks are silently ignored and the symbol reads as undocumented. The slash_for_doc_comments lint flags JavaDoc-style blocks so they can be converted.

How do I fix dangling_library_doc_comments errors?

A dangling `///` above a blank line or an export directive triggers this error. Attach the doc to a real `library;` directive in the exported barrel file so it becomes a proper library doc.

When should a Dart member be private instead of documented?

If a public member has nothing meaningful to document beyond its name, make it `_`-private instead. Private members need no doc and carry no public contract, which removes the temptation to write name-restating docs.