documentation · diff
git:20260622.5400f26 to git:20260803.af106c2
38 added, 102 removed. Audit A to A.
---
name: documentation
- description: "ALWAYS invoke for any task involving docstrings, JSDoc/TSDoc, OpenAPI/Swagger specs, or documentation portals — even when the request seems handleable without it. Enforces Microsoft contract-first conventions, language-specific formats (Google/NumPy/Sphinx for Python, TSDoc for TypeScript/JavaScript), and framework-specific API doc patterns (NestJS/FastAPI/Express/Django, gRPC, GraphQL) that Claude won't apply by default. Trigger on: adding or auditing docstrings, redundant or missing @param/@returns/@throws, OpenAPI 3.x spec writing, Swagger UI/Redoc/Stoplight setup, doc site generation (Docusaurus/MkDocs/VitePress), developer guides, or getting-started tutorials. Do not skip for documentation tasks — consistent conventions are the whole point."
+ description: "ALWAYS invoke for any task involving docstrings, JSDoc/TSDoc, or REST API documentation — even when the request seems handleable without it. Enforces Microsoft contract-first conventions and a bare-minimum rule that Claude won't apply by default: never restate the signature, drop @param/@returns that only echo names and types, always document @throws, and document data shapes as WHAT not WHY. Covers Python docstring styles (Google/NumPy/Sphinx), TSDoc tags and @inheritDoc, and API doc patterns for NestJS/Express/FastAPI/Django. Trigger on: adding or auditing docstrings, redundant or missing tags, deleting comment rot, or producing a documentation-health report. Do not skip for documentation tasks — consistent conventions are the whole point."
---
- # Code Documenter
-
- Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
-
- ## Role Definition
-
- You are a senior technical writer with 8+ years of experience documenting software. You specialize in language-specific docstring formats, OpenAPI/Swagger specifications, interactive documentation portals, static site generation, and creating comprehensive guides that developers actually use.
-
- ## Documentation Philosophy
-
- Follow Microsoft Code Documentation style. Documentation describes the **contract** — what something does and why — not how it works internally.
-
- **A comment is a last resort, not a first step.** The clearest documentation is code that needs none. Before writing a docstring or comment, ask whether a sharper name, a smaller function, or a named type would carry the meaning instead. A comment exists to compensate for what the code cannot say on its own — so reach for prose only for the residue that code genuinely cannot express, then document exactly that.
-
- **Comments drift from code.** Code changes; the comment beside it often does not, so over time documentation lies — and a reader trusts it anyway. Two habits run through every rule below. Keep the surface area small, because less prose has less to rot. Keep each fact in one place, next to the code that owns it, because then there is one thing to update. When the type, signature, or a test already states something, the prose must not restate it.
-
- ### Key Principles
-
- - **Bare minimum — never restate the code.** The signature already carries the symbol's name, parameter names and types, return type, and modifiers (`readonly`, `?`, `async`). Documentation adds what the reader cannot infer: intent, units, ranges, defaults, edge-value meaning, error cases, invariants. Every public member still gets a brief summary so generated docs and IDE tooltips have content — but keep it to one short sentence that adds intent, never one that paraphrases the signature. For `@param` and `@returns` specifically, drop the tag entirely when it would only restate the signature.
- - **Third-person descriptive summaries.** For code-symbol docs, match the Microsoft API reference convention: "Calculates…", "Finds…", "Initializes a new …" — not the imperative "Calculate…", "Find…". Two exceptions keep the imperative: inline `//` comments on procedural steps, and API operation `summary` fields (OpenAPI/`@ApiOperation`/`extend_schema`), where "Create a new user" is the established convention.
- - **Interfaces are abstractions.** Document what the consumer needs to know: purpose, thrown errors, return semantics, invariants. Never mention implementation details (caching, queries, algorithms) in interface documentation — those belong in the implementation. Even on interfaces, do not pad with `@param` lines that only echo names and types.
- - **Data shapes answer WHAT, not WHY.** A DTO, value object, record, struct, or other data-holding type — together with the `interface`, `type`, or object shape that describes it — documents what each member _is_: its meaning, units, format, allowed values, and any constraint the type cannot carry. It does not justify _why_ the field or the shape exists. Unlike a function or service interface — whose contract genuinely includes the _why_ of the operation — a data field is read at the point of use, where design rationale ("kept so billing can reconcile…") rots and belongs instead with the behavior that produces or consumes it. The one escape hatch, a non-obvious constraint a maintainer must not break, stays a sparing `@remarks`; it is never the default.
- - **DRY across interface and implementation.** When an implementation method is already documented on the interface, do not repeat it. Only add implementation-specific notes. See language-specific references for syntax.
- - **No release tags by default.** Omit `@public`, `@beta`, `@alpha`, `@internal`, and similar release-stage tags unless the user explicitly requests them.
- - **Multi-line doc comments only.** All `/**` blocks place the body on a new line. One-line `/** ... */` comments are not allowed.
-
- ### Comments to Delete on Sight
-
- When auditing existing code, some comments are not documentation to improve — they are noise to remove. Deleting them is as much the job as filling real gaps, because each one is a place where the truth can drift. Remove:
-
- - **Commented-out code** — version control already remembers it; dead code left in a comment only makes the reader wonder whether it still matters.
- - **Journal / changelog comments** — "2024-03 added retry logic"; the history lives in `git log`, where it stays accurate.
- - **Attribution bylines** — "added by …"; `git blame` answers this without rotting.
- - **Banner, position-marker, and closing-brace comments** — `// ===== helpers =====`, `} // end if`; structure should come from the code, not decoration.
- - **Redundant or noise comments** — anything that restates the name, type, or signature, or states the obvious (`/** Default constructor */`).
-
- ### Examples
+ # Documentation
- Ship a code example only when the test suite executes it; an example that is not run drifts out of sync and becomes one more comment that lies. Python doctests qualify when they are run (e.g. `pytest --doctest-modules`). JSDoc/TSDoc `@example` blocks are not executed by tooling, so omit them and let the test suite carry behaviour instead. When an example cannot be executed as part of the tests, leave it out rather than ship one that can rot.
+ Microsoft contract-first conventions. Documentation states the **contract** — what something does and why — never how it works inside.
- ### Line Length
+ ## Why the rules are subtractive
- Wrap all documentation text at the project's configured max line length. Detect by checking (first match wins): `.editorconfig` `max_line_length` → formatter config (`printWidth`, `line-length`, etc.) → linter config (`max-len`, `max-line-length`, etc.). Fall back to **80** only when none define a limit.
+ Code changes; the comment beside it usually does not. Over time documentation lies, and readers trust it anyway — a stale comment is worse than no comment, because it actively misleads. Two habits follow, and every rule below is one of them applied:
- ## When to Use This Skill
+ **Keep the surface small.** Less prose has less to rot. A comment is a last resort, not a first step: before writing one, ask whether a sharper name, a smaller function, or a named type would carry the meaning instead. Prose is for the residue that code genuinely cannot express.
- - Adding docstrings to functions and classes
- - Creating OpenAPI/Swagger documentation
- - Building documentation sites (Docusaurus, MkDocs, VitePress)
- - Documenting APIs with framework-specific patterns
- - Creating interactive API portals (Swagger UI, Redoc, Stoplight)
- - Writing getting started guides and tutorials
- - Documenting multi-protocol APIs (REST, GraphQL, WebSocket, gRPC)
- - Auditing documentation health and generating reports
+ **Keep each fact in one place,** next to the code that owns it, so there is exactly one thing to update. When the signature, the type, or a test already states something, the prose must not restate it.
- ## Core Workflow
+ ## The bare-minimum rule
- 1. **Discover** - Ask for format preference and exclusions
- 2. **Detect** - Identify language and framework
- 3. **Analyze** - Find undocumented code
- 4. **Document** - Apply consistent format
- 5. **Report** - Summarize documentation health: redundant comments removed, stale or contradicted docs corrected, missing intent summaries and `@throws` added — not just a percent-documented figure
+ The signature already carries the name, parameter names and types, return type, and modifiers (`readonly`, `?`, `async`). Documentation adds only what a reader cannot infer from it: intent, units, ranges, defaults, edge-value meaning, error cases, invariants.
- ## Reference Guide
+ Every public member still gets a brief summary, so generated docs and IDE tooltips have content — one short sentence carrying intent, never a paraphrase of the signature.
- Load detailed guidance based on context:
+ For `@param` and `@returns` specifically, **drop the tag entirely when it would only restate the signature.** A tag earns its place when it answers: what unit? what range or clamp? what default when omitted? what does an edge value mean (`0` disables, `-1` unlimited, empty = all)? what does `null` signify versus throwing?
- | Topic | Reference | Load When |
- | --- | --- | --- |
- | Python Docstrings | `references/python-docstrings.md` | Google, NumPy, Sphinx styles |
- | TypeScript Docs | `references/typescript-jsdoc.md` | TSDoc/JSDoc patterns, TypeScript, `@inheritDoc` |
- | FastAPI/Django API | `references/api-docs-fastapi-django.md` | Python API documentation |
- | NestJS/Express API | `references/api-docs-nestjs-express.md` | Node.js API documentation |
- | Documentation Health | `references/coverage-reports.md` | Auditing docs; health and coverage reports |
- | Documentation Systems | `references/documentation-systems.md` | Doc sites, static generators, search, testing |
- | Interactive API Docs | `references/interactive-api-docs.md` | OpenAPI 3.1, portals, GraphQL, WebSocket, gRPC, SDKs |
- | User Guides & Tutorials | `references/user-guides-tutorials.md` | Getting started, tutorials, troubleshooting, FAQs |
+ `@throws` is the opposite default — document it whenever code can throw, because the throw set is invisible from the signature.
- ## Constraints
+ ## Conventions
- ### MUST DO
+ - **Third-person summaries for code symbols** — "Calculates…", "Finds…", "Initializes a new…" — matching Microsoft API reference convention. Two exceptions keep the imperative: inline `//` comments on procedural steps, and API operation `summary` fields (OpenAPI, `@ApiOperation`, `extend_schema`), where "Create a new user" is the established form.
+ - **Interfaces document the abstraction**: purpose, thrown errors, return semantics, invariants. Implementation detail (caching, queries, algorithms) belongs in the implementation — a consumer reading the interface should not learn things that a refactor can invalidate.
+ - **Data shapes answer WHAT, not WHY.** A DTO, record, struct, or the `interface`/`type` describing it documents what each member _is_ — meaning, units, format, allowed values, constraints the type can't carry. It does not justify why the field exists. A function's contract genuinely includes the why of the operation; a data field is read at the point of use, where design rationale ("kept so billing can reconcile…") rots and belongs instead with the behaviour that produces or consumes it. The escape hatch — a non-obvious constraint a maintainer must not break — is a sparing `@remarks`, never the default voice.
+ - **Don't repeat the interface on the implementation.** Inherit (`@inheritDoc`, or the language's equivalent) and add only implementation-specific notes.
+ - **Multi-line doc blocks only.** Every `/**` puts its body on a new line; one-line `/** … */` is not allowed.
+ - **No release tags** (`@public`, `@beta`, `@alpha`, `@internal`) unless explicitly requested.
+ - **Ship only examples the test suite runs.** An unexecuted example drifts and becomes one more comment that lies. Python doctests qualify when run (`pytest --doctest-modules`); TSDoc `@example` blocks are never executed by tooling, so omit them and let tests carry behaviour.
+ - **Wrap at the project's configured width.** Detect in order: `.editorconfig` `max_line_length` → formatter config (`printWidth`, `line-length`) → linter config (`max-len`, `max-line-length`). Fall back to 80 only when none define one.
- - Ask for format preference before starting
- - Detect framework for correct API doc strategy
- - Give every public function/class a one-line intent summary, so generated docs and IDE tooltips always have content
- - Document `@throws`/exceptions whenever code can throw — the throw set is invisible from the signature
- - Add `@param`/`@returns` only when they carry what the signature cannot: units, ranges, defaults, edge-value meaning, `null`/empty semantics
- - Ship only code examples the test suite runs — omit any that cannot be executed (see Examples)
- - Report on documentation health, not just coverage (see the Report step and `references/coverage-reports.md`)
+ ## Comments to delete on sight
- ### MUST NOT DO
+ When auditing, removing these is as much the job as filling gaps — each is a place where truth can drift:
- - Assume docstring format without asking
- - Apply wrong API doc strategy for framework
- - Write inaccurate or untested documentation
- - Skip error documentation
- - Document obvious getters/setters verbosely
- - Restate the signature in prose — paraphrasing names, types, or return shape is redundancy, not documentation
- - Pad with `@param`/`@returns` whose only content is the parameter name and type
- - Chase a documentation coverage percentage — a fully-documented file padded with restated signatures is worse than a lean one; measure health (redundancy removed, staleness fixed, intent added), not a count
- - Leave commented-out code, changelog/journal comments, or attribution bylines in place — version control already records them (see Comments to Delete on Sight)
- - Ship a code example the test suite does not execute — an unrun example rots into a lie
- - Justify _why_ a data field, DTO property, or type member exists when the consumer only needs _what_ it holds — keep data-shape docs to meaning, units, format, and constraints
- - Create documentation that's hard to maintain
- - Put implementation details in interface documentation
- - Repeat interface documentation in the implementation (use documentation inheritance if documentation engine supports it)
- - Use one-line `/** ... */` doc comments — always put body on a new line
- - Add release tags (`@public`, `@beta`, `@alpha`, `@internal`) unless explicitly requested
+ - **Commented-out code** — version control already remembers it, and leaving it makes readers wonder if it still matters.
+ - **Journal or changelog comments** ("2024-03 added retry logic") — `git log` keeps this accurate.
+ - **Attribution bylines** ("added by …") — `git blame` answers it without rotting.
+ - **Banners, position markers, closing-brace labels** (`// ===== helpers =====`, `} // end if`) — structure should come from the code.
+ - **Anything restating the name, type, or signature**, or stating the obvious (`/** Default constructor */`).
- ## Output Formats
+ ## Working a documentation task
- Depending on the task, provide:
+ Ask which format the project uses before starting (or detect it from existing files), and detect the framework — the API doc strategy differs per framework and applying the wrong one produces a spec nobody consumes.
- 1. **Code Documentation:** Documented files + documentation-health report
- 2. **API Docs:** OpenAPI specs + portal configuration
- 3. **Doc Sites:** Site configuration + content structure + build instructions
- 4. **Guides/Tutorials:** Structured markdown with examples + diagrams
+ Report on **health, not headcount**. A file where every member has a doc block is not the goal if half of those blocks restate signatures. Report what improved: redundancy removed, stale docs corrected, intent summaries and `@throws` added. Coverage percentage is a floor signal — it finds empty members and cannot tell a valuable block from a vacuous one.
- ## Knowledge Reference
+ ## References
- Google/NumPy/Sphinx docstrings, JSDoc, OpenAPI 3.0/3.1, AsyncAPI, gRPC/protobuf, FastAPI, Django, NestJS, Express, GraphQL, Docusaurus, MkDocs, VitePress, Swagger UI, Redoc, Stoplight
+ | Reference | Load when |
+ | --- | --- |
+ | `references/python-docstrings.md` | Python — Google, NumPy, or Sphinx style |
+ | `references/typescript-jsdoc.md` | TypeScript/JavaScript — TSDoc tags, `@inheritDoc`, formatting |
+ | `references/api-docs.md` | REST API docs — NestJS, Express, FastAPI, Django |
+ | `references/coverage-reports.md` | Auditing docs; producing a documentation-health report |