Code Documenter

Overview

Analyzes source code to generate accurate, context-aware documentation at multiple levels: inline comments for complex logic, function/class docstrings, module-level overviews, architecture documents, and onboarding guides. Understands control flow, data transformations, side effects, and cross-module dependencies.

Instructions

When asked to document code:

Determine the documentation level needed:
- Inline: Function/method docstrings, JSDoc, Python docstrings, Go doc comments
- Module: README or header comment explaining the module's purpose and exports
- Architecture: High-level document showing how modules interact, data flows, key design decisions
- Onboarding: Getting-started guide for new team members
For function/method documentation, extract:
- Purpose: What does this function do? (one sentence)
- Parameters: name, type, description, default values, constraints
- Return value: type, description, possible values
- Side effects: database writes, API calls, file I/O, state mutations, cache invalidation
- Exceptions/errors: what can go wrong, when, and what error types
- Example usage: realistic call with realistic data
For complex logic, add inline comments explaining:
- WHY, not WHAT — explain the reasoning, not the obvious operation
- Business rules embedded in conditionals
- Performance-critical sections and why they're written a certain way
- Workarounds with links to issues/bugs if available in git history
- Non-obvious algorithm choices
For architecture documentation:
- Map module dependencies (imports/requires graph)
- Identify entry points (API handlers, CLI commands, event listeners)
- Trace key data flows through the system (e.g., "user signup" flow)
- Document configuration and environment variables
- List external service dependencies (databases, APIs, queues)
- Note design patterns used (repository pattern, event sourcing, CQRS, etc.)
Language-specific format:
- TypeScript/JavaScript: JSDoc with @param, @returns, @throws, @example
- Python: Google-style docstrings with Args, Returns, Raises sections
- Go: Package-level and exported function doc comments per Go conventions
- Java: Javadoc with @param, @return, @throws
- Rust: /// doc comments with # Examples sections
Quality rules:
- Never state the obvious ("Increments counter by 1")
- Document the contract, not the implementation (what, not how — unless the how is surprising)
- Include realistic example values, not foo, bar, test123
- Flag functions that are too complex and suggest refactoring before documenting
- Note when documentation reveals a likely bug (e.g., unhandled null case)

Examples

Example 1: Document a Python function

Input:

def process_payment(user_id, amount, currency, idempotency_key=None):
    user = db.users.find(user_id)
    if not user:
        raise ValueError("User not found")
    if user.balance < amount and not user.credit_enabled:
        return {"status": "declined", "reason": "insufficient_funds"}
    charge = stripe.charges.create(
        amount=int(amount * 100),
        currency=currency,
        customer=user.stripe_id,
        idempotency_key=idempotency_key
    )
    db.transactions.insert({
        "user_id": user_id, "amount": amount,
        "stripe_charge_id": charge.id, "created_at": datetime.utcnow()
    })
    if user.balance < amount:
        user.balance = user.balance - amount
        db.users.update(user)
    return {"status": "success", "charge_id": charge.id}

Output:

def process_payment(user_id, amount, currency, idempotency_key=None):
    """Process a payment by charging the user's Stripe account.

    Validates the user's balance (unless credit is enabled), creates a Stripe
    charge, records the transaction, and deducts from the user's internal balance
    if applicable.

    Args:
        user_id: Internal user identifier (e.g., "usr_8f2k3j").
        amount: Charge amount in major currency units (e.g., 49.99).
        currency: ISO 4217 currency code (e.g., "usd", "eur").
        idempotency_key: Optional key to prevent duplicate charges on retry.
            Recommended for all production calls.

    Returns:
        dict: {"status": "success", "charge_id": "ch_..."} on success,
              {"status": "declined", "reason": "insufficient_funds"} if balance
              is too low and credit is not enabled.

    Raises:
        ValueError: If user_id does not match any user in the database.
        stripe.error.CardError: If the card is declined by Stripe.
        stripe.error.InvalidRequestError: If Stripe parameters are invalid.

    Side Effects:
        - Creates a Stripe charge (external API call)
        - Inserts a row into the transactions table
        - May update the user's balance

    Example:
        >>> result = process_payment("usr_8f2k3j", 49.99, "usd", idempotency_key="pay_retry_001")
        >>> result
        {"status": "success", "charge_id": "ch_3Kx9mPqR2s"}

    Note:
        ⚠ Potential bug: balance deduction only happens when balance < amount,
        but the charge always goes through. If balance >= amount, the user is
        charged via Stripe but their internal balance is not deducted.
    """

Example 2: Generate architecture overview