/annotate

Add inline documentation (JSDoc, docstrings, comments) to under-documented code.

Steps

1. Read the target file and assess current documentation level. 2. Identify what needs documentation:

• Public functions and methods lacking doc comments.
• Complex logic blocks without explanatory comments.
• Non-obvious parameter types or return values.
• Module-level overview missing.

3. Generate documentation in the appropriate format:

• TypeScript/JavaScript: JSDoc with `@param`, `@returns`, `@throws`, `@example`.
• Python: Google-style or NumPy-style docstrings.
• Go: Godoc comments above exported functions.
• Rust: `///` doc comments with examples.

4. For each function, document:

• What it does (one-sentence summary).
• Parameters with types and descriptions.
• Return value description.
• Thrown exceptions or error conditions.
• Usage example for complex functions.

5. Add a module-level doc comment explaining the file's purpose. 6. Verify the documentation does not break the build or linter.

Format

/**
 * Creates a new user account with the given credentials.
 *
 * @param email - The user's email address (must be unique)
 * @param password - Plain text password (will be hashed)
 * @returns The created user object with generated ID
 * @throws {ConflictError} If a user with this email already exists
 * @example
 * const user = await createUser("alice@example.com", "securePass123");
 */

Rules

• Document intent and contracts, not implementation details.
• Every public function must have at minimum a summary and parameter descriptions.
• Do not add comments that merely restate the code.
• Use the project's existing documentation style if one is established.
• Include `@example` for functions with non-obvious usage patterns.