tomevault-io 为模块编写测试和文档
何时使用
- 为新模块或新接口补充单元测试。
- 为已有模块补齐中文文档。
- 重构或扩展行为后，需要同步更新测试与文档。
- 需要把“语义与行为”整理成专业、简洁的 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补齐测试和中文文档，只描述语义和行为，不解释实现。 - 为某个新同步原语新增测试文件和文档页面，并更新当前仓库需要的导航与构建入口。
- 审查一个模块现有测试和文档，指出缺失的行为覆盖与文档语义漏洞。
Source: pointertobios/asco — distributed by TomeVault.