DEV Community

myougaTheAxo
myougaTheAxo

Posted on

Generate Documentation with Claude Code: API Docs, READMEs, and Code Comments

#claudecode #documentation #typescript #productivity

Keeping documentation up to date is one of those tasks that always slips. Claude Code can generate it from code, and with a few constraints, the output is actually useful.

1. API Reference Docs from Code

Point Claude Code at your route handlers or controller files:

Generate OpenAPI/Swagger documentation for these API endpoints.
Include:
- Endpoint path and HTTP method
- Request body schema (infer from validation code)
- Response schema (infer from return types/examples)
- Error responses (400, 401, 404, 500)

Router file:
[paste the file]
Enter fullscreen mode Exit fullscreen mode

For TypeScript with Express:

Generate JSDoc comments for each handler function in this router.
Include @param for request, @returns for response type,
@throws for error cases.

[paste the router]
Enter fullscreen mode Exit fullscreen mode

2. README Generation 

Generate a README.md for this project. Include:
- One-sentence description
- Prerequisites
- Installation steps (use the actual commands from package.json)
- Environment variable setup (use .env.example)
- Running locally
- Running tests
- Project structure (top-level directories only)
- Contributing guide

Context:
[paste CLAUDE.md or package.json]
Enter fullscreen mode Exit fullscreen mode

The output is a working README. You edit to add context, not write from scratch.

3. Code Comments for Complex Logic

For algorithmically complex code:

Add comments to this function explaining:
1. What the function does (single-line summary)
2. The algorithm/approach (inline comments at key steps)
3. Why non-obvious decisions were made

Do NOT comment obvious lines. Only add comments where
the logic isn't self-evident.

[paste the function]
Enter fullscreen mode Exit fullscreen mode

The "do NOT comment obvious lines" constraint is crucial — otherwise you get:

// Increment i by 1
i++;
Enter fullscreen mode Exit fullscreen mode

4. Changelog Generation 

Generate a changelog entry for these git commits.
Format: Keep a Changelog (https://keepachangelog.com/)
Categorize as Added/Changed/Fixed/Removed.

Commits:
[paste git log output]
Enter fullscreen mode Exit fullscreen mode

Or use this directly:

git log --oneline v1.2.0..HEAD | claude -p "Convert to Keep a Changelog format"
Enter fullscreen mode Exit fullscreen mode

5. CLAUDE.md for Documentation Rules 

## Documentation Rules

### When to Comment
- Algorithm explanation (why this approach)
- Non-obvious business logic
- Workarounds (explain what's being worked around)
- Performance-critical sections (explain the optimization)
- Never for: self-explanatory code, obvious operations

### JSDoc/Docstrings
- Required for: public functions, exported types, complex private functions
- Not required for: private simple helpers, test utilities

### README
- Keep README.md at project root up to date
- API changes must update the OpenAPI spec in `docs/openapi.yaml`
- Architecture decisions in `docs/adr/` (Architecture Decision Records)
Enter fullscreen mode Exit fullscreen mode

6. Architecture Decision Records (ADR)

For capturing why architectural decisions were made:

We decided to use Prisma instead of TypeORM for database access.
Generate an Architecture Decision Record (ADR) documenting this decision.

Include:
- Context (what problem we were solving)
- Options considered
- Decision
- Consequences (positive and negative)
Enter fullscreen mode Exit fullscreen mode

Store ADRs in docs/adr/ and reference them from CLAUDE.md so Claude Code understands past decisions.

7. Hook: Enforce Comment Quality 

# .claude/hooks/check_comments.py
import json, sys, re

data = json.load(sys.stdin)
content = data.get("tool_input", {}).get("content", "") or ""

# Detect obvious/useless comments
bad_patterns = [
    r'//\s*increment [a-z] by 1',
    r'//\s*set [a-z]+ to',
    r'//\s*return [a-z]+',
    r'//\s*print ',
    r'//\s*log ',
]

issues = [p for p in bad_patterns if re.search(p, content, re.IGNORECASE)]
if issues:
    print(f"[DOCS] {len(issues)} obvious comment(s) detected - remove or improve", file=sys.stderr)
    # Warning only, don't block
sys.exit(0)
Enter fullscreen mode Exit fullscreen mode

Documentation automation tips: use /refactor-suggest to identify code that needs documentation, and /code-review to catch missing docs before PRs.

Code Review Pack (¥980) on PromptWorks.

👉 prompt-works.jp

Myouga (@myougatheaxo) — Security-focused Claude Code engineer.

Top comments (0)