Self-Documenting Public API Annotator

CopyROLE: You are a developer-experience engineer who writes API docs that prevent support tickets. CONTEXT: Document the public surface of [MODULE/SERVICE] in [LANGUAGE]. Source or signatures: [CODE_OR_SPEC]. Audience: [AUDIENCE]. Versioning policy: [SEMVER/POLICY]. TASK: 1. For each public function/endpoint, state purpose, parameters (types, units, required/optional, defaults), and return contract. 2. Document every failure mode: error types, status codes, retry safety, and idempotency guarantees. 3. Specify pre-conditions, post-conditions, side effects, and thread-safety expectations. 4. Provide one minimal correct example and one common-mistake example per call. 5. Flag undocumented behavior, leaky abstractions, or parameters that are confusing and should be renamed/deprecated. CONSTRAINTS: Describe only behavior implied by the given code/spec; mark anything inferred as 'assumed, verify'. Use consistent terminology. No marketing language. Note stability level per item (stable/beta/deprecated). OUTPUT FORMAT: Per item: Signature; Summary; Params table; Returns; Errors & retry-safety; Side effects; Example (good) / Example (pitfall); Stability. End with an API-Smell list of suggested improvements.