用途:处理涉及 docstring、JSDoc/TSDoc 或 REST API 文档的任务,强制执行 Microsoft 契约优先约定。文档只说明契约——做什么、为什么,不写内部实现。
主要能力:用减法规则约束文档。缩小书写面,注释是最后手段,先考虑更好的命名、更小的函数或具名类型;每个事实只保留一份,紧邻拥有它的代码,签名、类型或测试已表达的不得重复。
写作要求:签名已承载名称、参数名与类型、返回类型和修饰符时,文档只补充读者无法推断的信息:意图、单位、范围、默认值、边界值含义、错误情况、不变式。每个公开成员仍需一句简短摘要承载意图。@param 与 @returns 若只是复述签名则整个标签删除;@throws 相反,只要代码可能抛出就记录。
结构预算:摘要恰好一行一句;细节最多三行,且仅当摘要无法承载契约时使用;行内注释最多三行,一行优先。溢出说明内容放错位置,分支行为、边缘情况和约束理由应放入 @remarks(Python 用 Note: / Notes)。以格式化后的实际渲染行数为准计数。
语言风格:写作时加载 simple-english 技能,同一概念全文件用同一词;描述句 25 词、命令句 20 词为上限;用 can、will、must,不用 should;条件在前结果在后;无度量支撑的形容词删除;标识符、代码示例、错误字符串保持精确。
约定:代码符号用第三人称摘要;接口记录抽象,实现细节留给实现;数据形状回答 WHAT 不回答 WHY;实现处用 @inheritDoc 继承而不重复接口;只允许多行文档块;非明确要求不加发布标签;只提供测试套件会运行的示例;按项目配置宽度换行。
使用方式:开始前先确认项目使用的格式与框架(或从现有文件检测),REST API 文档按框架选择不同策略;审计时删除被注释代码、日志式注释、署名、分隔横幅和复述签名或显而易见的内容;报告改进而非覆盖率数字。参考资料按需加载:Python docstring、TypeScript JSDoc、REST API 文档、覆盖率报告。
限制:资料未提供具体价格、平台、安装命令与效果数据。