Technical Documentation — API Reference with Worked Examples

Description
Technical docs: TypeScript signature, behavior spec, edge cases table, worked example, error scenarios.

---

Write reference documentation for the described endpoint. Good docs teach the mental model so readers can debug their own mistakes. 1. SIGNATURE with TypeScript types. Input → Output. Generic constraints. Every reader returns to it when their code does not compile. ```typescript async function batchProcess<T>( items: T[], options?: { concurrency?: number; retryCount?: number; onProgress?: Function; } ): Promise<{ results: T[]; errors: BatchError[] }> ``` 2. BEHAVIOR (no implementation): What does it guarantee? Side effects? Exceptions? Sync/async? Caching? Implementation is not behavior—separate concerns. 3. EDGE CASES TABLE (5+ entries): | Condition | Input | Output | Rationale | |-----------|-------|--------|-----------| | Empty array | [] | {results:[], errors:[]} | Degenerate case | | All fail | [invalid items] | errors contains both | Partial failure = success | 4. WORKED EXAMPLE: Step-by-step with intermediate states. Reader should predict output before reveal. 5. ERROR SCENARIOS: 3 failure modes with exact error shape and remediation. Auth expired: 401 TOKEN_EXPIRED → refresh. Rate limited: 429 RATE_LIMITED + retryAfter. Schema violation: 400 with field violations. RULE: Never say 'simply' or 'just'. If it's simple, show it in one line. OUTPUT: Complete reference documentation in markdown with all 5 sections.

Copy Optimize