注释生成
为非显然函数生成文档注释；跳过平凡并避免噪声。
文档与重构入门
为什么
GitHub 2024 调查发现 81% 的开发者预期 AI 工具未来一年在代码文档中更深度集成，为所有工作流中最高。好文档注释助读者与 AI 上下文；坏的（'x 加 1'）是噪声。
仅对非显然函数生成，含意图 + 边界，增信号而不杂乱。
何时使用
用于未文档化的非平凡函数。平凡 getter/setter 跳过。
如何做
1. 列无文档注释的函数。
2. 提示："加 JSDoc 含 @param/@returns 与意图；跳过显然的；含边界"。
3. 逐个审查；删任何仅重述代码的。
4. 跑 tsc（strict 模式检查 JSDoc）。
5. 提交 docs: add JSDoc to <module>。
示例
之前：export const parsePage = (input: string | null): number => { ... }
之后：
/** 将 ?page= 参数解析为 1 起页（最小 1）；null/无效 → 1。 */
export const parsePage = (input: string | null): number => { ... }
跳过：export const getId = (x: { id: string }) => x.id; // 显然，无注释。
常见问题
- ⚠重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。
- ⚠错误：重构后 "Cannot read properties of undefined" → 跑测试套件（`npm test`）捕获行为变更；重构须保持行为。
- ⚠错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。
最佳实践
- ✓文档意图与边界，非代码做什么。
- ✓跳过平凡函数；噪声伤可读性。
- ✓用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。
常见问题解答
什么是注释生成？
为非显然函数生成文档注释；跳过平凡并避免噪声。 它可帮助开发者快速理解 注释生成 的核心价值与适用场景。
如何开始使用注释生成？
开始使用 注释生成，建议先掌握以下要点：列无文档注释的函数。
注释生成 的常见误区有哪些？
使用 注释生成 时常遇到的问题包括：重构后 Error: Cannot find module 'xxx' → 重跑 `npm install` 和 `npx tsc --noEmit`；重构常丢或重命名 import。；错误：重构后 "Cannot read properties of undefined" → 跑测试套件（`npm test`）捕获行为变更；重构须保持行为。；错误：文档漂移：示例无法运行 → 在 CI 执行示例（`npm run docs:check`）；被测示例不会漂移。。
注释生成 的最佳实践是什么？
注释生成 的最佳实践包括：文档意图与边界，非代码做什么。；跳过平凡函数；噪声伤可读性。；用具体指标衡量结果（节省时间、缺陷率、测试覆盖率），使实践可被论证和改进。。
如何深入学习注释生成？
从官方文档入手，再在 GitHub 上搜索真实示例；先在小实验仓库验证模式，再应用到生产代码。