doc-gen · diff
git:20260329.6c378a2 to git:20260503.631b94d
48 added, 161 removed. Audit A to A.
---
name: doc-gen
description: >-
Documentation generator with three modes: function-level (JSDoc/docstrings),
module-level (directory READMEs), and API reference (endpoints/exports).
Reads existing project doc style and matches it. Never generates docs that
just restate what the signature already says.
user-invocable: true
auto-trigger: false
trigger_keywords:
- document
- docs
- docstring
- jsdoc
- readme
- api docs
last-updated: 2026-03-20
---
# /doc-gen — Documentation Generator
- ## Identity
-
- You are a documentation writer who reads code deeply enough to explain what
- the signature alone cannot. You match the project's existing documentation
- style — if the codebase uses terse JSDoc, you write terse JSDoc. If it uses
- narrative READMEs with examples, you write narrative READMEs with examples.
- You never produce boilerplate that a reader could derive faster by reading
- the code itself.
-
- ## Orientation
+ ## When to Use
- Use `/doc-gen` when you need to:
- Add JSDoc/docstrings to functions in a file or set of files
- Write a README for a module or directory
- Document an HTTP API or exported library surface
- The skill auto-detects mode from the target:
- - **File path** (e.g., `src/utils/parser.ts`) → function-level mode
- - **Directory path** (e.g., `src/utils/`) → module-level mode
- - **Route file or API directory** (e.g., `api/`, `routes.ts`) → API reference mode
+ Mode auto-detected from target:
+ - **File path** → function-level mode
+ - **Directory path** → module-level mode
+ - **Route file or API directory** → API reference mode
- **Explicit override**: `/doc-gen --mode function|module|api [target]`
## Commands
| Command | Behavior |
|---|---|
| `/doc-gen [file]` | Function-level docs for a file |
| `/doc-gen [directory]` | Module-level README for a directory |
| `/doc-gen --api [target]` | API reference for endpoints or exports |
| `/doc-gen --mode [mode] [target]` | Force a specific mode |
| `/doc-gen --dry-run [target]` | Show what would be documented without writing |
## Protocol
### Phase 1: DETECT STYLE
- Before writing a single doc comment, read the project's existing documentation:
-
- 1. Read CLAUDE.md for project conventions and doc expectations
- 2. Search for existing doc comments in the target area and adjacent files:
- - JSDoc style: `/** ... */` with `@param`, `@returns`, etc.
- - TSDoc style: similar but with `@remarks`, `@example`, etc.
- - Python docstrings: Google style, NumPy style, or Sphinx style
- - Inline `//` comments used for documentation
- 3. Note the style attributes:
- - **Density**: Every function, or only public API?
- - **Tone**: Terse technical, or narrative with context?
- - **Tags used**: Which `@` tags appear? Are `@example` blocks common?
- - **Line length**: Short single-line descriptions, or multi-line paragraphs?
- 4. If no existing docs exist in the project, default to:
- - TypeScript/JavaScript: JSDoc with `@param`, `@returns`, `@throws`, `@example`
- - Python: Google-style docstrings
- - Other languages: idiomatic doc comment format for that language
+ 1. Read CLAUDE.md for doc conventions
+ 2. Search for existing doc comments in the target area — note density, tone, tags used, and line length
+ 3. Default when no existing docs: JSDoc (`@param`, `@returns`, `@throws`, `@example`) for TS/JS; Google-style for Python; idiomatic format for others
- Store the detected style and apply it consistently across all generated docs.
+ Apply detected style consistently across all generated docs.
### Phase 2: ANALYZE TARGET
#### Function-Level Mode
- For each function in the target file:
-
- 1. Read the full function body, not just the signature
- 2. Classify the function:
- - **Trivial**: Simple getters, setters, identity transforms, one-line wrappers
- with obvious names (e.g., `getName()`, `setCount(n)`, `toString()`).
- SKIP these — a doc comment adds noise, not information.
- - **Non-trivial**: Everything else. Document these.
- 3. For non-trivial functions, identify:
- - **Purpose**: What problem does this solve? Why does it exist?
- - **Parameters**: Types are visible in TS — document *semantics*, not types.
- Bad: `@param id - the id`. Good: `@param id - User account ID, used for DB lookup and auth token generation`.
- - **Return value**: What does the caller get? What shape, what guarantees?
- - **Throws/errors**: What can go wrong? Under what conditions?
- - **Side effects**: Does it mutate state, write to disk, emit events, call APIs?
- - **Non-obvious behavior**: Edge cases, performance characteristics, ordering
- dependencies, nullable returns, empty array vs undefined semantics
- - **Example**: Include `@example` when the usage is non-obvious — when the
- function has complex parameters, returns a structure, or has a setup requirement
+ For each function:
- 4. Write the doc comment using the detected style
+ 1. Read the full body, not just the signature
+ 2. Classify:
+ - **Trivial**: simple getters/setters, one-line wrappers with obvious names — SKIP
+ - **Non-trivial**: document purpose, parameter semantics (not types — TS has those), return guarantees, throws/errors, side effects, non-obvious edge cases, and `@example` when usage is non-obvious
+ 3. Write using detected style
- **The core rule: every doc must add information beyond what reading the
- function signature and name already tells you.** If you cannot say anything
- the signature does not already say, do not write a doc comment for that function.
+ **Core rule:** every doc must add information beyond what the signature already says. If you cannot, skip it.
#### Module-Level Mode
- For the target directory:
-
- 1. Read all files in the directory (and one level of subdirectories)
- 2. Identify the module's role:
- - What problem space does it own?
- - What are its key exports (public API)?
- - What are its internal implementation files?
- - What are its dependencies (imports from outside the module)?
- - What depends on it (search for imports of this module)?
- 3. Structure the README:
-
- ```markdown
- # {Module Name}
-
- {One-paragraph description of what this module does and why it exists.}
-
- ## Key Exports
-
- | Export | Description |
- |---|---|
- | `{name}` | {what it does, when to use it} |
-
- ## Architecture
-
- {Only include this section if the module has non-obvious internal structure.
- Describe the key files and how they relate. Mention any patterns used
- (state machine, pub/sub, pipeline, etc.).}
-
- ## Usage
-
- {Code examples showing how to import and use the module's public API.
- Use real import paths from the project.}
-
- ## Dependencies
-
- {What this module depends on and why. Only list non-obvious dependencies —
- skip standard library and ubiquitous packages.}
- ```
-
- 4. If a README already exists, update it rather than replacing it.
- Preserve any sections the existing README has that your analysis
- doesn't cover (e.g., "Known Issues", "Migration Guide").
+ 1. Read all files in the directory (one level deep)
+ 2. Identify: problem space, key exports, internal files, external dependencies, and what imports this module
+ 3. README schema: `# {Module Name}` | one-paragraph description | `## Key Exports` table (name, description) | `## Architecture` (only if non-obvious internal structure) | `## Usage` (real import paths) | `## Dependencies` (non-obvious only)
+ 4. If a README already exists, update rather than replace — preserve sections not covered by your analysis
#### API Reference Mode
- For HTTP APIs (route files, API directories):
-
- 1. Read all route/endpoint definitions
- 2. For each endpoint, document:
- - **Method + Path**: `GET /api/users/:id`
- - **Description**: What it does
- - **Parameters**: Path params, query params, request body (with types)
- - **Response**: Success shape (with example), status codes
- - **Errors**: Error codes and their meanings
- - **Authentication**: Required auth level, if applicable
- - **Example**: curl or fetch example for non-trivial endpoints
-
- For exported libraries:
+ For HTTP endpoints: method + path, description, path/query/body params (with types), response shape and status codes, errors, auth level, and a curl/fetch example for non-trivial endpoints.
- 1. Read all public exports
- 2. For each export, document:
- - **Name and type**: function, class, constant, type
- - **Description**: Purpose and usage context
- - **Parameters/Properties**: With types and semantics
- - **Return type**: With guarantees
- - **Example**: Import and usage
+ For exported libraries: name and kind (function/class/constant/type), description, parameters/properties with semantics, return type with guarantees, import and usage example.
Structure as a single reference document with a table of contents.
### Phase 3: WRITE
- 1. Apply the detected style consistently
- 2. For function-level: insert doc comments directly above each function
- 3. For module-level: write or update README.md in the target directory
- 4. For API reference: write to a location that makes sense for the project
- (e.g., `docs/api/`, or adjacent to the route files)
- 5. Run typecheck after writing to ensure doc comments don't break anything
- (malformed JSDoc can cause TS errors)
+ 1. Apply detected style consistently
+ 2. Function-level: insert doc comments above each function
+ 3. Module-level: write or update README.md in the target directory
+ 4. API reference: write to `docs/api/` or adjacent to route files
+ 5. Run typecheck after writing (malformed JSDoc can cause TS errors)
### Phase 4: VERIFY
- 1. Re-read every doc comment you wrote
- 2. For each one, ask: "Does this tell the reader something they couldn't
- get from the signature alone?" If no, delete it.
- 3. Check for accuracy: does the doc match what the code actually does?
- Pay special attention to:
- - Parameter descriptions that don't match actual parameter names
- - Return type descriptions that don't match actual return types
- - Documented side effects that don't exist (or undocumented ones that do)
- - Examples that wouldn't actually compile/run
+ Re-read every doc comment. For each: "Does this add information beyond the signature?" If not, delete it. Check accuracy: parameter names, return types, side effects, and that examples would actually compile/run.
+ ## Contextual Gates
+
+ **Disclosure:** "Generating documentation for [target]. Source files will be modified."
+ **Reversibility:** amber — adds JSDoc/docstrings to source files; undo with `git checkout` on modified files.
+ **Trust gates:**
+ - Any: additive doc generation on undocumented functions.
+ - Familiar (5+ sessions): rewriting existing docstrings that may discard prior content.
+
## Quality Gates
- - **Information density**: Every doc comment must add information beyond the signature.
- "Returns the user ID" on `getUserId(): string` is a failure. Delete it.
- - **Accuracy**: Docs must match actual code behavior. A wrong doc is worse than no doc.
- - **Style consistency**: All generated docs must match the project's existing style.
- If the project uses `@returns` not `@return`, use `@returns`.
- - **No boilerplate**: Never generate `@param name - The name` style filler.
- If a parameter's name fully describes it and there is nothing else to say, omit it
- from the doc or describe its constraints/semantics.
- - **Typecheck clean**: Inserted doc comments must not break the build.
- - **Trivial skip rate**: At least some functions should be skipped as trivial.
- If you documented every single function including obvious getters, you over-documented.
+ - Every doc comment adds information beyond the signature; if not, delete it
+ - Docs match actual code behavior — wrong docs are worse than no docs
+ - Style matches the project's existing convention throughout
+ - No `@param name - The name` filler; omit parameters when their name is self-explanatory
+ - Typecheck passes after insertion
+ - At least some functions skipped as trivial — if every function was documented, you over-documented
## Exit Protocol
- Report what was documented:
-
```
=== Doc-Gen Report ===
-
Mode: {function-level | module-level | api-reference}
- Target: {file or directory path}
- Style: {detected style description}
-
- Documented:
- - {N} functions in {file} ({M} skipped as trivial)
- OR
- - README.md written for {directory} ({N} exports, {M} sections)
- OR
- - API reference: {N} endpoints documented
-
- Skipped:
- - {function/file}: {reason — trivial, already documented, etc.}
+ Target: {path}
+ Style: {detected style}
+ Documented: {N functions ({M} skipped as trivial) | README.md ({N} exports) | {N} endpoints}
+ Skipped: {item}: {reason}
```
```
---HANDOFF---
- Generated {mode} docs for {target}
- Matched existing {style} convention
- - {key decisions: what was skipped and why}
+ - {what was skipped and why}
+ - Reversibility: amber — undo with `git checkout` on modified source files
---
```