SuperAPI AI 工具集

doc-comment-writer

通用与其它

查看项目

更新于 10-16 01:49

技能介绍

用途:为代码撰写、修订或精简面向未来维护者的持久文档注释,帮助其理解用途、契约、约束与非显然决策,而不必从实现中反推。当没有适用的语言专属技能时使用,支持多语言。

主要能力:先明确作用范围与本地约定,推断该语言常规的文档注释形式、文件既有风格与注释密度。必要时查看邻近类型、测试、调用方或同类文件,以理解公开行为或重要不变量。对每个在范围内的符号与已有注释做出保留、新增、修订、删除或跳过的明确决定。仅在删除会丢失读者相关信息时保留旧注释;修订过时或晦涩的注释;删除仅复述声明或实现的注释。文件级注释在职责、边界或用法模式从名称与导出看不出来时添加,保持简短结构化。

注释标准:说明保证、副作用、失败模式、生命周期预期、不变量、边界、误用风险或持久权衡。以代码、类型、配置作为易变事实(阈值、超时、默认值、常量、成员列表、文件名、路径)的唯一来源,用语义规则描述而非把字面量抄进文字。外部引用视为例外,不引用计划、进度、交接、临时决策日志或 issue/PR 讨论;持久理由应写进注释本身,仅当存在权威且稳定维护的规范或契约时才引用。避免时间相对措辞与易过时的分步实现细节。对从代码推断的行为保守表述,不臆造实现不支持的意图或保证;无法从仓库证据确立重要理由时,提出聚焦的维护者问题而非写推测性注释。

使用方式:遵循用户声明的范围,参照文件既有风格与注释密度,应用上述标准撰写或修订每条新注释;仅当局部不变量或微妙分支需要超出文档注释能承载的解释时才用行内注释。完成后运行最相关的格式化、解析、lint、文档或示例检查;若都没有,则检查改动后的注释语法并报告该限制。编辑后用简短报告说明新增、修订、删除的注释,值得注意的跳过决定,验证情况,以及因代码不清晰而提出的聚焦问题。除非用户同时要求重构,否则保持 diff 聚焦于文档。

适用场景:多语言代码库中公开符号、文件或模块边界、类型语义与生命周期、以及执行棘手不变量、协议或规范化规则的内部辅助代码。

限制:会跳过仅复述文件名、平凡访问器与包装、参数或类型叙述、直白控制流及大段抄自实现的注释。资料未提供具体命令、安装方式或价格信息。