documentation

Documentation Patterns

Domain expertise for documentation quality and alignment. Use alongside devflow:review-methodology for complete documentation reviews.

Iron Law

DOCUMENTATION MUST MATCH REALITY

Outdated documentation is worse than no documentation. It actively misleads. Every code change that affects behavior requires a documentation check. Comments that explain "what" instead of "why" are noise. The best documentation is code that doesn't need documentation.

---

Documentation Categories

1. Code Documentation Issues

Issue	Problem	Fix
Missing docstrings	Complex functions without explanation	Add JSDoc with params, returns, throws
Outdated comments	Comments that contradict code	Update or remove
"What" comments	// Loop through users	Explain "why" instead
Magic algorithms	Complex logic without explanation	Document algorithm and rationale
Transition residue	"We no longer do X" notes, in-file changelogs, or refs to removed code/sections	Remove — git holds the history

Brief Example - Missing vs. Complete:

// BAD: No documentation on complex function
export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;

// GOOD: Purpose, params, returns, edge cases documented
/**
 * Calculates prorated billing amount when switching plans mid-cycle.
 * @param plan - The new plan to prorate to
 * @returns Prorated amount in cents (can be negative for downgrades)
 */
export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;

2. API Documentation Issues

Issue	Problem	Fix
Missing params	Callers don't know valid values	Document all params with types and constraints
Missing returns	Return shape unknown	Describe return structure and units
Missing errors	Callers don't know what to catch	List all thrown error types

Brief Example - Incomplete vs. Complete:

// BAD: No params, no errors documented
/** Creates a subscription. */
async function createSubscription(userId: string, planId: string): Promise<Subscription>;

// GOOD: Full contract documented
/**
 * @param userId - User's unique identifier
 * @param planId - Plan ID from /plans endpoint
 * @throws {UserNotFoundError} If userId doesn't exist
 * @throws {PlanNotFoundError} If planId doesn't exist
 */
async function createSubscription(userId: string, planId: string): Promise<Subscription>;