高质量异步函数文档需明确执行时机、错误契约、并发安全与可测试性：标注后台任务/惰性执行/事件循环影响；结构化错误类型与触发条件；声明状态共享风险与幂等性；提供含异常处理的可运行示例及测试提示。
高质量的异步函数文档与 API 规范，核心不是罗列代码，而是让使用者一眼看懂“它何时执行、如何失败、怎样并发、怎么测试”。重点在于暴露异步行为的契约细节，而非掩盖它。
明确标注异步行为与执行语义
不能只写“返回 Promise”或“支持 await”，要说明实际执行时机和控制权归属：
- 注明是否启动后台任务（如
setTimeout、setInterval、事件监听注册），还是纯粹等待外部 I/O 完成 - 说明是否“立即启动”还是“惰性执行”——例如
async function fetchUser() { return api.get('/user') }是调用即发起请求；而async function lazyFetch() { return () => api.get('/user') }则需二次调用才触发 - 标注是否受事件循环调度影响：比如使用
queueMicrotask或Promise.resolve().then()的函数，其回调会在当前宏任务末尾执行，而非下一轮事件循环
错误路径必须结构化呈现
异步错误不是“可能抛异常”，而是有明确触发条件和形态，文档需逐条对应：
- 列出每种错误类型对应的 Promise 拒绝值：是
new Error实例？还是带code和details字段的普通对象？ - 区分网络层错误（如 fetch 失败、超时）、业务逻辑错误（如 token 过期、权限不足）、数据解析错误（如 JSON.parse 失败）
- 给出可复现的触发方式示例，如：“当传入
timeout: 100且响应耗时超过 100ms 时，拒绝值为{ code: 'TIMEOUT', message: 'Request timed out' }”
并发与状态安全需显式声明
异步函数常被多处调用，文档必须澄清共享状态风险：
- 说明是否线程/协程安全：多个并发调用是否会互相干扰？例如共用一个
loading标志或缓存变量 - 标注是否幂等：重复调用是否产生相同副作用（如发两次邮件）？还是具备自动去重机制？
- 若函数内部维护状态（如节流器、重试计数器），需说明该状态生命周期——是单例级、实例级，还是每次调用隔离？
提供可验证的调用示例与测试提示
示例不是装饰，而是降低上手门槛的最小可行验证：
- 给出完整可运行的调用片段，包含
try/catch或.catch()，并展示成功与典型失败场景的输出 - 注明推荐的 mock 方式：如 “测试超时场景，请使用
jest.useFakeTimers()并调用jest.runOnlyPendingTimers()” - 提示关键断言点：例如 “应验证最终状态是否为
idle，而非仅检查返回值” 或 “需断言是否调用了localStorage.setItem一次”
