# 注释规范 本规范适用于本仓库的 TypeScript、JavaScript、TSX/JSX、脚本与配置。新增或修改注释时必须遵循;不为自解释代码机械补注释。参考用户指定的统一注释风格,按 Ray Template 的组件与模块边界调整。 ## 组件与文件说明 - 不在文件顶部、`defineComponent` 前或函数组件声明前添加多行介绍性注释。组件职责、继承关系、用法与示例放在相应 README;非显然约束放在实际受影响的位置。 - 不把文件介绍移动到第一个函数、常量或导出对象前。注释必须描述紧邻声明的真实契约,不能借换位置保留整段文件说明。 - 同一个声明只保留一份契约说明,禁止连续堆叠多个 JSDoc 块。 ## 函数与方法契约 确有需要说明参数、资源所有权、副作用、异步归属或失败语义时,使用多行 JSDoc。参数、返回值以实际签名与实现为准。 1. 使用独立的 `/**` 和 ` */`,内部每行以 ` *` 开头,并与被说明的声明对齐。 2. 开头先放一行仅含 ` *` 的空白注释行;区段之间也使用这样的空白行,不保留行尾空格。 3. 标签按 `@param` → `@description` → `@returns` → `@throws` 排列,仅保留需要的区段。 4. 有参数时按签名顺序列出真实参数名与含义;多个 `@param` 连续排列。无参数时省略参数区。 5. `@description` 独占一行,正文从下一行开始,不在标签前重复写一段函数介绍。 6. `void`、`Promise` 和构造函数不写 `@returns`;副作用放在描述区。`@throws` 只描述调用方可观察的抛出或 Promise 拒绝。 ```ts /** * * @param wait 页面恢复前的等待时间,单位为毫秒 * * @description * 重新挂载当前页面;恢复计时器由 Store 持有,避免随页面卸载而取消。 */ const reload = (wait = 800) => { // 实现省略。 } ``` 公开 Hook 的完整示例优先放在 README 与可运行示例页,不在函数前堆放长篇教程。历史 `@example` 不应在无关任务中机械删除;本次修改契约时应同步核对它是否仍准确。 ## 声明与逻辑说明 - 模块级常量、变量、类字段和类型属性的简短说明使用单行 JSDoc `/** 说明 */`,不加标签。 - 类、接口或类型确需说明整体职责时,使用带开头空白行的多行 JSDoc,正文放在独占一行的 `@description` 后,不虚构参数或返回值。 - 函数内部的分支、局部变量、执行顺序和原因说明使用 `//`;多行逻辑说明逐行写 `//`,不套用函数契约格式。 - 注释用中文解释非显然的原因与约束,技术标识符保留原名。避免逐行复述、作者闲谈、过时行为和没有实现依据的保证。 ```ts /** 内容区恢复前的默认等待时间,单位为毫秒 */ const RELOAD_DELAY = 800 const update = () => { // 页面可能已被替换,执行时再读取当前布局实例。 const layout = contentRef.value } ``` 许可证、来源归属、生成标记和工具指令保留其必要语法,例如 `// @ts-expect-error`、`/// `、`/* @__PURE__ */`。JSX 子节点使用 `{/* 说明 */}`;HTML、CSS 使用各自合法的定界符。 交付前检查注释位置、是否堆叠、参数名、标签顺序和内容真实性。注释规范不替代 ESLint、Prettier、类型检查或浏览器验收。