JSDoc

Add JSDoc only where a careful reader cannot infer intent, constraints, or failure modes from names and types alone. Prefer TypeScript types for shape; use JSDoc for why, when, and what breaks.

When to Document

Document a symbol when any of these are true:

• Control flow, algorithm, or state machine is non-obvious on first look.
• Behavior depends on invariants, ordering, timing, idempotency, or concurrency.
• Side effects matter (I/O, mutation, cache, network, timers, global state).
• Failure modes, throws, empty results, or partial success are part of the contract.
• Units, ranges, formats, or domain meanings are not clear from the type.
• Public / exported API that callers will use without reading the implementation.
• Deprecation, migration, security, or compatibility constraints apply.

When Not to Document

Skip JSDoc when: