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