Ask Claude to Add JSDoc or Docblock Comments to Your Undocumented Functions

Writing doc comments by hand is tedious, and auto-generated ones just repeat the function signature. Claude reads the actual implementation — the edge cases, the error conditions, the side effects — and writes documentation that adds real value.

Add JSDoc comments to all exported functions in src/services/ that don't 
have them. Read the implementation and document what each function actually 
does, not just what the types say.

Claude produces comments that go beyond the signature:

/**
 * Processes a refund for an order, prorating the amount if only
 * some items are returned. Sends a notification email on success.
 *
 * @param {string} orderId - The order to refund
 * @param {string[]} [itemIds] - Specific items to refund. Omit for full refund.
 * @returns {Promise<RefundResult>} The refund details including transaction ID
 * @throws {OrderNotFoundError} If the order doesn't exist
 * @throws {AlreadyRefundedError} If the order was already fully refunded
 * @example
 * // Full refund
 * await processRefund('ord_123');
 * // Partial refund
 * await processRefund('ord_123', ['item_456']);
 */

This works for all documentation formats:

# PHPDoc
Add PHPDoc blocks to all public methods in app/Services/. 
Include @param, @return, @throws, and a description that explains 
the business logic, not just the mechanics.

# Python docstrings
Add Google-style docstrings to all functions in src/. Include Args, 
Returns, Raises, and a usage Example for complex functions.

# Targeted documentation
Only document the functions that other developers call — the public 
API surface. Skip private helpers and internal utilities.

After adding docs, ask Claude to verify accuracy:

Check that every @throws annotation matches an actual throw in the code. 
Check that every @param matches an actual parameter. Remove any 
documentation that doesn't match the implementation.

Good documentation describes intent and edge cases, not just types — let Claude read the code and write comments that help the next developer understand why.

via Claude Code