document

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

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