Document — Auto-Documentation

When to Trigger

• New public function, class, or API endpoint
• Function signature changed (params added/removed)
• Module purpose unclear from code alone
• User explicitly asks for documentation

Process

1. Detect what changed

• New exports? → Add JSDoc/docstring
• Changed params? → Update existing docs
• New file? → Add module-level doc comment

Why: Undocumented changes are the most common source of onboarding friction. Catching every diff ensures no public surface is left without context.

2. Write docs

Follow the project's existing doc style. If none exists:

TypeScript/JavaScript:

/**
 * Brief description of what this does.
 *
 * @param name - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this happens
 *
 * @example
 * const result = myFunction("input");
 */

Python:

def my_function(name: str) -> str:
    """Brief description.

    Args:
        name: Description of parameter.

    Returns:
        Description of return value.

    Raises:
        ValueError: When this happens.
    """

Why: Consistent doc style across the project reduces cognitive load for every reader. Inlining examples prevents the "how do I call this?" round-trip.

3. Don't over-document

• Skip obvious getters/setters
• Skip internal/private helpers unless complex
• Code should be self-documenting first, comments second

Why: Noise docs train readers to ignore all comments. Document only where the code cannot speak for itself.

Anti-Rationalization

Evidence Required

Before claiming documentation is done, show ALL applicable:

• Every new public function/class has a doc comment (show one example)
• Changed signatures have updated docs (show the diff)
• @param / @returns / @throws present for non-trivial functions
• At least one @example for complex APIs

"I added docs" without showing them = not documented.

Red Flags

• Comments that restate the code: // increment i → i++
• Outdated comments that contradict the code
• Missing docs on public API that others will call