doc-gen

/doc-gen — Documentation Generator

When to Use

• 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

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

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

Apply detected style consistently across all generated docs.

Phase 2: ANALYZE TARGET

Function-Level Mode

For each function:

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

Core rule: every doc must add information beyond what the signature already says. If you cannot, skip it.

Module-Level Mode

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