用途:该技能面向代码内文档写作,涵盖文件夹 README、JSDoc 注释与代码注释,核心原则是文档解释“为什么”而非“是什么”。当用户提出“document this”“add JSDoc”“write a README”“explain this code”,或需要撰写 README.md/JSDoc 时使用;语气遵循 writing-voice。架构讲解、文件夹心智模型或面向新人的说明,应先给出归属者、边界或流程,再落到代码,并在有帮助时点出常见误解。
文件夹 README:首要任务是解释该文件夹为何存在及其心智模型。开头给出有用的模型:这个文件夹负责什么、为何存在、未来改动应保留什么边界。可包含:用 ASCII 图示表达复杂关系、关键导出或入口点概览、在文件名之外能补充上下文的简要文件说明、与其他文件夹的关系。应避免:只是复制 ls 的详尽文件清单;重复文件名的描述(如“auth.ts - 认证”);更适合用代码表达的实现细节。示例把转换器模式用图示与说明讲清楚,优于只罗列文件名。
JSDoc 注释:说明何时、为何使用某物,而非仅描述其行为。好例子会说明该方法对需要遍历所有表的 provider 和 index 有用、只返回表 helper 而不含 clearAll 等工具方法,并附 @example 现实用法。规则:包含真实感的 @example;解释何时使用而非仅做什么;记录非显然行为或边界情况;公共 API 详细,内部 helper 可精简。
代码注释:注释解释“为什么”。好例子说明 Y.Doc clientID 是随机 32 位整数、不能依赖顺序,因此改用条目自身时间戳做确定性排序。规则:代码清晰就不注释;不明显时注释“为什么”;为 workaround 附上 issue/文档链接;删除被注释掉的代码,交给 git 管理。
限制:资料未提供安装命令、平台支持、收费或价格信息,暂未提供。