从代码注释写出可用文档：一次小范围的整理实践

先选一个能独立说明的函数

从代码注释生成文档，最容易省掉的是组织语言的时间，最不能省的是核对行为的时间。先选一个自己熟悉、已有测试的小函数，例如计算订单折扣的函数。这次只写清它的用途、输入、输出和限制，让第一份文档能够独立使用。

阅读函数说明、参数注释和关键分支，再对照实现与测试。假如注释写着折扣可以叠加，实现却只取最大折扣，就先确认哪个才是预期行为。把已经确认的事实与尚待确认的问题分开，避免模型把过时注释改写成语气肯定的说明。

提交给模型的材料包括函数实现、相关注释，以及覆盖正常输入和异常输入的测试。如果行为取决于另一个函数，只补充必要部分。删除密钥、个人信息和无关代码。材料越聚焦，越容易发现遗漏，也能减少输入用量。

先要求模型只依据材料整理用途、参数约束、返回结果、异常和边界条件，并把无法确认的内容列为问题。人工补齐这些问题后，再让它写成面向使用者的说明。明确要求不要推测性能保证或兼容范围，避免得到看似完整、实际没有依据的承诺。

检查文档中的每项描述是否能在实现或测试中找到依据。折扣函数可以用普通订单验证计算结果，再用空订单或临界金额验证边界。示例结果要实际计算或通过测试确认。如果读者仍需猜测金额单位、取整方式或失败时的返回值，就继续补充说明。

需要反复修改时，只提交有变化的段落和相关依据。通过 MyRelay 调用模型后，可以查看每次请求的用量与费用，比较小范围整理的实际开销，再决定是否扩大处理范围。你可以创建一个 MyRelay 账户，从这一个函数开始记录成本。

最后，把文档与代码变更一起保存，并在评审时核对两者是否一致。以后参数、默认值或异常行为发生变化，就同步检查对应段落，让注释、实现与文档持续描述同一件事。