document

name: document description: apply documentation philosophy — explain why, not what. use for jsdocs, READMEs, inline comments.

apply documentation philosophy: explain why, not what.

when to use

writing jsdocs for components or functions
updating README or project docs
adding inline comments during implementation
reviewing existing documentation for cleanup

workflow

check if documentation is needed — if it describes obvious behavior, skip it
identify the non-obvious why: design constraints, behavioral consequences, inheritance warnings
write terse, lowercase prose
delete anything that merely restates the code

quick reference: why over what

delete this:

/** context provider that wraps children in a DisclosureProvider. */

keep this:

/**
 * blocks CompositeContext so nested Lists create isolated focus loops.
 * essential for "Simple API" goal — our List is "greedy" and would
 * otherwise join parent's arrow-key navigation.
 */

what to document

design rationale and constraints
context shadowing / inheritance warnings
non-obvious behavioral consequences
internal decisions affecting correctness

what to delete

obvious behavior ("renders a button")
what the function name already says
what types already express

jsdoc structure

/**
 * one-line description of purpose or behavior.
 *
 * additional context if design rationale is complex (keep brief).
 *
 * @prop propName - what it does
 * @example
 * ```tsx
 * <Component>content</Component>
 * ```
 */

maintainer notes

preserve @bdsqqq notes or similar when they explain non-obvious decisions:

/**
 * @bdsqqq notes: alpha colors avoided for strokes due to compounding
 * overlap issues at intersection points.
 */

colocate context with code

jsdocs are source of truth. upon finishing a task, colocate valuable context as jsdocs — only notes that explain non-obvious why. delete everything else.

tone

lowercase only (ALL CAPS for emphasis)
terse, no unsupported claims
specific over general; describe, don't emote