In-code documentation, folder READMEs, and code comments. Use when the user says "document this", "add JSDoc", "write a README", "explain this code", or when writing README.md files, JSDoc comments, or code organization docs.
Follow writing-voice for tone.
Documentation explains why, not what. Users can read code to see what it does. They need you to explain the reasoning.
Use this pattern when you need to:
README.md files with architecture intent.Primary job: explain why this folder exists and the mental model.
ls# Converters
Transform field schemas into format-specific representations.
```
┌─────────────┐ ┌──────────────┐
│ Field Schema│────▶│ to-arktype │────▶ Runtime validation
└─────────────┘ ├──────────────┤
│ to-drizzle │────▶ SQLite columns
└──────────────┘
```
Field schemas are pure JSON Schema objects with `x-component` hints. Each converter takes the same input and produces output for a specific consumer.
# Converters
- `to-arktype.ts` - Converts to ArkType
- `to-drizzle.ts` - Converts to Drizzle
- `index.ts` - Exports
The bad example just lists files without explaining the pattern or when to add new converters.
JSDoc explains when and why to use something, not just what it does.
/**
* Get all table helpers as an array.
*
* Useful for providers and indexes that need to iterate over all tables.
* Returns only the table helpers, excluding utility methods like `clearAll`.
*
* @example
* ```typescript
* for (const table of tables.defined()) {
* console.log(table.name, table.count());
* }
* ```
*/
defined() { ... }
/** Returns all table helpers as an array. */
defined() { ... }
@example blocks with realistic usageComments explain why, not what.
// Y.Doc clientIDs are random 32-bit integers, so we can't rely on ordering.
// Use timestamps from the entries themselves for deterministic sorting.
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);
// Sort the entries
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);