Code Documenter

Code Documenter

When to Use / When Not to Use

Use when:

• Functions and classes lack docstrings, JSDoc, or KDoc
• An existing API needs an OpenAPI/Swagger spec
• The project needs a documentation site (Docusaurus, MkDocs, VitePress)
• Writing tutorials, user guides, or troubleshooting docs

Do not use when:

• You need architectural decision documentation (use technique-write:adr-writer)
• You need a documentation strategy plan (use documentation-strategy)

Process

1. Discover — Ask for format preference and exclusions. If unspecified, inspect the codebase for existing conventions first; default to Google style (Python) or JSDoc (TypeScript/JS) if none found.
2. Detect — Identify language and framework
3. Analyze — Find undocumented public functions, classes, and API endpoints
4. Document — Apply consistent format across all targets
5. Validate — Test all code examples compile/run:
   • Python: python -m doctest file.py or pytest --doctest-modules
   • TypeScript/JavaScript: tsc --noEmit
   • OpenAPI: npx @redocly/cli lint openapi.yaml
6. Report — Generate coverage summary. Flag any file below 70% function coverage or any API endpoint below 100% coverage.

Output Template

What Claude Does / What You Do

Quick-Reference Examples

Google-style Docstring (Python)

def fetch_user(user_id: int, active_only: bool = True) -> dict:
    """Fetch a single user record by ID.

    Args:
        user_id: Unique identifier for the user.
        active_only: When True, raise an error for inactive users.

    Returns:
        A dict containing user fields (id, name, email, created_at).

    Raises:
        ValueError: If user_id is not a positive integer.
        UserNotFoundError: If no matching user exists.
    """

JSDoc (TypeScript)

/**
 * Fetches a paginated list of products from the catalog.
 *
 * @param {string} categoryId - The category to filter by.
 * @param {number} [page=1] - Page number (1-indexed).
 * @returns {Promise<ProductPage>} Resolves to a page of product records.
 * @throws {NotFoundError} If the category does not exist.
 */
async function fetchProducts(categoryId: string, page = 1): Promise<ProductPage> { ... }

Reference Guide

Constraints

MUST DO:

• Ask for format preference before starting (or detect from existing code)
• Document all public functions and classes
• Include parameter types, descriptions, and exception docs
• Test all code examples in documentation
• Generate a coverage report

MUST NOT DO:

• Assume docstring format without asking or detecting
• Write inaccurate or untested documentation examples
• Skip exception/error documentation
• Document obvious getters/setters verbosely

Related Skills

• technique-write:adr-writer — for documenting architectural decisions
• documentation-strategy — for planning a documentation system
• code-documenter + frontend-developer — generate JSDoc alongside React component builds