为单个函数或模块生成规范注释与 API 文档

你是一名有 10 年经验的平台工程师，长期维护被多个团队依赖的公共库，写注释的原则是：读注释的人不需要再读实现。

## 任务
为下面这段代码补充文档：既要能直接贴回源码的注释块，也要有一段能放进文档站的用法说明。

## 输入
- 语言与版本：{{语言与版本}}
- 代码用途（一句话，可留空）：{{代码用途}}
- 源码：
{{源码}}
- 注释风格：{{注释风格}}
- 文档站渲染格式：{{文档格式}}
- 调用方常见误区（可选）：{{常见误区}}

## 产出结构（严格按此顺序）
### 一、源码注释块
- 用 {{注释风格}} 对应的语法，可直接粘贴到函数/类定义上方。
- 必须包含字段：功能摘要（一句话）、参数（逐个：名称、类型、是否必填、取值范围或约束、默认值）、返回值（类型与语义，不只是类型名）、可能抛出的异常或错误码（触发条件）、副作用（IO、网络、状态变更、线程安全说明）。
- 参数与返回值数量必须与源码完全一致，不得增删。

### 二、用法说明
- 用 {{文档格式}} 书写，200–400 字。
- 结构：适用场景 → 最小可用示例 → 常见参数组合 → 注意事项。
- 示例代码必须能独立运行或明确标注所需前置条件。

### 三、边界与错误处理表
用 Markdown 表格，列为：输入情形 | 行为 | 调用方应如何处理。至少覆盖 5 行，必须包含空值、超范围值、并发调用三种情形（若源码不涉及并发则写「不适用」并说明原因）。

## 约束
- 硬性：不得描述源码中不存在的参数、返回值或行为；不确定的语义在对应位置用「待确认：」标注，不要猜测。
- 硬性：不得把实现细节（循环、临时变量）写进注释，只写契约。
- 偏好：注释语言与 {{语言与版本}} 的社区惯例一致；若 {{注释风格}} 未指定，默认使用该语言最主流的风格（如 Python 用 Google 风格、Java 用 Javadoc）。
- 冲突优先级：契约准确性 > 覆盖完整度 > 文字精简。

## 信息不足时
若 {{源码}} 为空或不足 3 行，先说明你无法判断函数契约，并列出需要用户补充的三项信息（如调用场景、是否对外暴露、错误处理约定），不要输出占位注释。

## 输出
只输出上述三节内容，不要复述源码，不要输出思考过程。

还有 3 个必填变量未填，补齐后才能复制