doc-gen

Generate documentation for the code specified in $ARGUMENTS. The argument may be a file path, a directory, a function name, or a keyword like "readme" or "api".

Step 1 — Determine Documentation Type

Parse $ARGUMENTS to figure out what kind of documentation is needed:

Argument contains	Action
A file path (e.g., src/auth.ts)	Add inline JSDoc/docstrings to that file
A directory (e.g., src/utils/)	Document all exported members in that directory
readme or README	Generate or update the project README
api	Generate API reference documentation
A function/class name	Find and document that specific symbol
Nothing	Ask the user what they want documented

Step 2a — Inline Documentation (JSDoc / Docstrings)

For each exported function, class, method, type, and constant in the target file(s):

JavaScript/TypeScript — JSDoc:

/**
 * Brief one-line description of what this function does.
 *
 * Longer explanation if the behavior is non-obvious, including
 * algorithm notes, performance characteristics, or caveats.
 *
 * @param name - Description of the parameter
 * @returns Description of the return value
 * @throws {ErrorType} When and why this error is thrown
 * @example
 * const result = myFunction("input");
 * // result === "expected output"
 */

Python — Docstrings (Google style):

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

    Longer explanation if needed.

    Args:
        name: Description of the parameter.

    Returns:
        Description of the return value.

    Raises:
        ValueError: When and why this error is raised.

    Example:
        >>> my_function("input")
        'expected output'
    """

Rules:

• Do not state the obvious. @param id - The id is useless. Write @param id - Unique identifier used to look up the user record.
• Document why, not just what, when the purpose is non-obvious.
• Include at least one @example for public API functions.
• Document thrown errors and edge-case behavior.
• Preserve existing documentation — only add or improve, never remove unless it is incorrect.