API Reference Writer (From Source Code)

Generate API reference documentation from the source code below. Document ONLY the public surface; ignore internals. For every public function/method/endpoint: ### `name(parameters) -> return type` - **Purpose**: one sentence, what it does for the caller (not how it works inside). - **Parameters**: each with type, whether optional, default, and constraints (ranges, formats, units — read them from the code, e.g. validation logic and guard clauses). - **Returns**: type and shape, including what happens on empty/missing results (null? empty list? throws?). - **Errors**: every exception/error the code can actually raise, with its trigger condition. Read the code paths — do not invent generic errors. - **Example**: a minimal runnable snippet with realistic values and expected output. - **Notes**: surprising behavior found in the code — mutation of inputs, caching, retries, thread-safety assumptions, side effects. This section is the most valuable one; look hard. Rules: - Derive everything from the code. If behavior is ambiguous from the source, write "TODO: verify — <specific question>" rather than guessing. - Order entries by likely frequency of use, not alphabetically. - Output clean Markdown. ```{{language}} {{code}} ```