asco-test-doc

name	asco-test-doc
description	为 ASCO 模块编写单元测试与中文文档。用于新增模块、补齐测试覆盖、补写 API/模块说明、整理行为语义说明。重点产出 tests 下的用例与 docs/zh-cn/src 下的专业文档，文档只描述语义、约束和可观察行为，不描述实现细节。
argument-hint	说明目标模块、需要覆盖的公开接口、是否已有实现，以及文档目标页或章节

为模块编写测试和文档

何时使用

• 为新模块或新接口补充单元测试。
• 为已有模块补齐中文文档。
• 重构或扩展行为后，需要同步更新测试与文档。
• 需要把“语义与行为”整理成专业、简洁的 API 说明，而不是实现解读。

目标产出

• 至少一个针对目标模块的测试源文件，或对现有测试文件的增量补充。
• 如有新增测试文件，更新 tests/CMakeLists.txt 以纳入统一 tests 目标。
• 一份或多份中文文档页面，放在 docs/zh-cn/src/ 下的合适位置；默认不产出英文文档。
• 如有新增页面，更新 docs/zh-cn/src/SUMMARY.md 与对应章节 README.md 的导航入口。

输入信息

开始前先确认这些信息；若缺失，先向用户追问：

• 目标模块或头文件路径。
• 需要覆盖的公开类型、函数、错误条件或并发语义。
• 这次是“新增测试和文档”，还是“只补测试”或“只补文档”。
• 文档是新增页面还是修改现有页面。

工作流程

1. 建立语义边界

先阅读目标模块及其相邻测试、文档，整理以下内容：

• 模块暴露了哪些公开接口。
• 每个接口的成功路径、失败路径和边界条件。
• 是否存在异步、取消、阻塞、并发访问、panic 或 guard 生命周期等特殊语义。
• 哪些行为对调用方可观察，哪些只是内部实现细节。

如果无法只凭现有代码判断公开语义，暂停并向用户确认，不要擅自把内部实现推断写进文档。

2. 设计测试矩阵

围绕“可观察行为”列出测试点，优先覆盖：

• 基本成功路径。
• 边界输入与空值路径。
• 失败返回、异常或 panic 路径。
• 状态转换与资源释放。
• 并发或异步模块的时序约束、取消、互斥和唤醒行为。

测试命名应直接对应行为，不要用含糊名称。

3. 实现或补充测试

遵循当前仓库的测试习惯：

• 使用 ASCO_TEST(...) 定义用例。
• 使用 ASCO_CHECK(...) 断言，并让错误信息直接说明预期与实际。
• 异步条件优先使用有界等待或 yield 轮询，不依赖无边界阻塞。
• 后台任务、定时器或可取消任务在失败路径需要清理。
• 不共享未同步的全局可变状态。

决策规则：

• 如果目标行为已有对应测试文件，优先在原文件中补充，保持主题集中。
• 如果目标模块尚无合适测试文件，创建新的测试源文件，并同步更新 tests/CMakeLists.txt。
• 如果行为依赖 runtime、时间或调度，测试应显式约束等待边界，避免挂死。

4. 编写或更新文档

文档只描述语义、约束和行为，不描述实现过程、内部数据结构或优化策略。

写作要求：

• 语言专业、简洁、直接。
• 先给出模块职责，再按接口或能力分节。
• 对每个接口说明调用条件、返回语义、失败语义和重要约束。
• 示例代码默认可选；只有在接口用法不直观、容易误用或缺少示例会明显影响理解时才补充最小示例。
• 若存在易误用点，写“语义约束”或“使用建议”，不要写成实现备注。

避免写入以下内容：

• 内部锁策略、具体调度算法、容器布局等实现细节。
• “源码中如何做到”的过程性解释。
• 没有稳定语义承诺的推测性描述。

5. 维护文档导航

新增文档页面时检查：

• docs/zh-cn/src/SUMMARY.md 是否已加入入口。
• 所属章节的 README.md 是否需要补充链接。

若本次只更新已有页面，不要无意义调整其他导航结构。

6. 结束前自检

提交前逐项检查：

• 测试是否覆盖了主要成功路径、失败路径和边界条件。
• 文档是否只描述语义与行为，没有落入实现细节。
• 新增测试文件是否已加入 tests/CMakeLists.txt。
• 新增文档页面是否已加入中文文档导航。
• 名称、术语和返回语义是否与现有代码一致。

完成标准

满足以下条件才算完成：

• 测试与文档都与目标模块的公开行为一致。
• 测试失败信息可直接定位行为不符点。
• 文档读者无需阅读实现即可理解如何使用该模块，以及会观察到什么行为。
• 文档没有把内部实现细节误写成 API 语义。

如果用户没有说明，不应将以下内容作为完成标准：

• 格式化代码。
• 运行测试。

常见分支

只有接口声明，没有稳定实现

• 可以先写文档骨架和行为预期。
• 测试仅写已经确定的公开契约；未定部分先向用户确认。

只有实现，没有测试和文档

• 先从公开入口逆推出可观察行为。
• 先补测试，再整理文档，避免文档描述与实际行为脱节。

行为涉及并发与取消

• 优先验证最终可观察结果与边界时序。
• 谨慎处理跨挂起点对象生命周期，不要把引用参数直接带入协程边界行为说明。

推荐提示词

• 为 asco/sync/mutex.h 补齐测试和中文文档，只描述语义和行为，不解释实现。
• 为某个新同步原语新增测试文件和文档页面，并更新当前仓库需要的导航与构建入口。
• 审查一个模块现有测试和文档，指出缺失的行为覆盖与文档语义漏洞。