document

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

1. •check if documentation is needed — if it describes obvious behavior, skip it
2. •identify the non-obvious why: design constraints, behavioral consequences, inheritance warnings
3. •write terse, lowercase prose
4. •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