# dartdoc-conventions

> Claude/Codex skill by [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars · Updated 2026-09-23

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.

Tags: agent-skills, ai-agents, best-practices, claude-code, codex, coding-agent, cursor, dart, dartlang, developer-tools, drift, flutter, flutter-architecture, github-copilot, go-router, llm, material-design, mvvm, riverpod, skills

## Install

```sh
git clone https://github.com/zakariaf/Flutter-Skills /tmp/Flutter-Skills && ln -s /tmp/Flutter-Skills/skills/dartdoc-conventions ~/.claude/skills/dartdoc-conventions
```

## From README

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. publicmemberapidocs 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. ///, never / /. Dartdoc only recognizes ///. A JavaDoc block is silently ignored and the symbol reads as undocumented. slashfordoccomments flags it.

## Links

- HTML page: https://omgskills.com/library/zakariaf/flutter-skills/skills/dartdoc-conventions/
- GitHub: https://github.com/zakariaf/Flutter-Skills
- Author: [@zakariaf](https://omgskills.com/library/zakariaf/index.md)

## More from this repo

- [accessibility-as-code](https://omgskills.com/library/zakariaf/flutter-skills/skills/accessibility-as-code/index.md) — Enforces accessibility as a correctness property authored into each widget — Semantics(button/label) or...
   - [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars
- [adaptive-layout](https://omgskills.com/library/zakariaf/flutter-skills/skills/adaptive-layout/index.md) — Enforces adapting layout by available CONSTRAINTS/size, never device or platform checks — LayoutBuilder +...
   - [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars
- [ads-and-iap-monetization](https://omgskills.com/library/zakariaf/flutter-skills/skills/ads-and-iap-monetization/index.md) — Enforces opt-in, rewarded-first monetization over the service seam — a rewarded view grants exactly one benefit and...
   - [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars