| name | comment-writer |
| description | Write and unify JSDoc, inline comments, and file headers following the project's established style. Use when adding or editing code comments. |
Comment Writer
按项目既有风格为代码补写、改写、统一 JSDoc 和行内注释。
参考基线
写作前先读取目标附近最邻近的现有注释：
- 目标文件本身的现有 JSDoc 和注释
- 同目录或相邻模块下的现有注释
- 同一层级中最接近目标职责的说明文本
归纳稳定写法后再落笔。
文件头格式
所有源码文件头部统一为：
@file — 简短的文件名或职责描述@description — 一句话说明文件职责，必须打句号@module — 路径格式为 {kernel|canvas|host|ui|io|cli}/{path/to/module}，与源码路径对应（各包根目录即前缀）@author — 作者名。不确定时执行 git config user.name
测试文件
测试文件（.test.js）不应写 @module。原因：
- 测试不被其他模块导入，
@module 对文档生成和模块图无贡献
- 测试和被测试文件天然配对（
foo.test.js 就在 tests/ 里紧挨 foo.js），路径关系一目了然
@module 路径和 .test.js 后缀的命名冲突增加了维护噪音
文件头只需要 @file、@description（可选）和 @author，例如：
check-module-paths.mjs 会自动跳过 .test.js 文件。
作者名可执行 git config user.name、git config --global user.name 获取。
单行示例：
多行示例：
注意多行时 @description 之后不可跟文字，正文从下一行开始。
JSDoc 规范
所有新增或修改的下列实体都要写 JSDoc：
通用规则
- JSDoc 正文使用中文，类型名、术语按代码原名保留
@description 必须打句号@description 只有一行时，正文跟在标签后面；如果正文有多行（含一段以上的描述），标签必须单独一行，正文从下一行开始，不可在 @description 后直接跟文字@description 之外的标签（@param、@returns、@throws、@type、@todo 等），一句话时不打句号，多句话时要打句号- 无标签的第一行描述（函数/类职责，紧接
/** 之后），一律不打句号。需多句描述时，改用 @description 标签承载详细内容。
- 优先延续相邻代码既有写法
字段和属性
禁止单行 /** @type {xxx} */ 格式。字段和属性的 JSDoc 必须使用多行格式，第一行写描述（不打句号），@type 单独一行：
isModifyingGestureActive = false;
_anchorPosition = null;
@type 之前的描述行不可省略——即使变量名已能表达含义，仍需写中文描述。
方法
方法注释优先写：
- 职责 — 这个方法做什么
- 参数语义 — 每个
@param 的含义
- 返回值语义 —
@returns 的含义
- 异常条件 —
@throws 的条件
不要重复实现细节。
示例：
applyModifiedObjects(modificationContext, objects) { ... }
类和构造函数
class CommonObjectModifierTool extends GestureBasedObjectModifierTool {
constructor(options = {}) { ... }
常量和枚举
const OBJECT_CREATOR_SIGNAL_TYPES = Object.freeze({
POSITION: "position",
GESTURE_END: "end",
...
});
事件
事件通过 Tool.on(name, callback) / Tool._emit(name, ...) 机制发布。事件 JSDoc 格式：
afterCompleteCreatedObject(interaction, completedObject) {
this._emit("afterCreate", interaction, completedObject);
}
访问控制标签
@private — 以下划线 _ 开头的方法或属性@protected — 子类可访问的方法- 大多数公开方法不需要显式标记
@public
状态标记
@abstract — 抽象方法或类@deprecated — 已废弃的 API，需说明替代方案@todo — 待完善事项
行内注释
- 一句话时不打句号
- 多句话时要打句号
- 只注释读代码时不明显的意图、约束、阶段性策略或数据转换原因
- 不要把代码逐行翻译成自然语言
工作方式
- 先找最近的现有样本，归纳目标文件当前风格
- 只在目标范围内补注释，不顺手重写无关内容
- 如果现有代码和注释存在偏差，以当前实现为准
- 如果信息不足以写出准确注释，保留最小化、可验证的描述，不要编造行为
- 优先产出可直接提交的结果，而不是泛泛建议
禁止事项
- 不要发明工作区里不存在的抽象、流程或状态机
- 不要把注释写成教程式长文
- 不要引入和周边文件明显不一致的注释风格
- 不要为了"完整"而补写未经代码证实的设计意图
- 不要使用装饰性分隔线注释块。禁止任何形式的纯装饰分隔线，包括但不限于：
- 连续字符围栏：
// ---- / // ===== / // ****
- 行首行尾装饰：
// -- xxx ---- / // == xxx === / // ** xxx **
- 其他任何仅为视觉分割而无信息量的注释行
