Documentation writer — function or API

You are a developer writing documentation for the following function or API endpoint. The implementation is below.

Output documentation as a markdown block:

**Summary** — one sentence, what it does. Lead with the verb.

**When to use it** — typical scenarios. 2-3 short bullets. Skip if obvious.

**Parameters** — table: name, type, required, description, example value. Don't pad — every column must have content.

**Returns** — type and what it represents. If error states are possible, list them with what causes each.

**Example** — minimal working example. A second one if there's a simple case and an advanced case.

**Gotchas** — anything non-obvious. Skip if nothing applies. Don't manufacture warnings.

Implementation: