用途:为 Valibot 库 /library/src/ 下的源代码编写 JSDoc 注释与内联文档,适用于 schema、action、method 或工具函数的文档化。
主要能力与约定: 接口文档首行写成“[Name] [category] interface.”,属性注释以“The”开头、以句号结尾,属性用 readonly,注释与属性间不留空行。 函数重载每个都要有完整 JSDoc:首行“Creates a [name] [category].”,描述后空行;@param 以“The”开头、句号结尾,参数后空行;@returns 写“A [name] [category].”或“The [description].”。 可在主描述与 @param 之间加 Hint,如 object schema 提示 looseObject 与 strictObject 区别;可用 markdown 链接外部资源。 实现函数不加 JSDoc,纯函数加 // @NO_SIDE_EFFECTS(用于打包工具 tree-shaking),会修改参数的函数(如 _addIssue)不加。 内部工具使用 @internal 标签并以 _ 前缀命名。 内联注释用于描述下一段代码做什么,用现在时动词、省略冠词、句末不加句号、注释前空行;条件逻辑用“If [condition], [action]”与“Otherwise, [action]”。Hint 注释是例外,可含冠词,解释原因而非动作。TODO 以“TODO:”开头。@ts-expect-error 用于 TypeScript 无法追踪的内部 dataset 变更。
文件类型模式:schema 文件含 issue 接口、schema 接口、带完整 JSDoc 的重载、带 // @NO_SIDE_EFFECTS 的实现及含内联注释的 '~run' 方法;action 文件类似;method 文件逻辑更复杂、内联注释更多;utility 文件为单函数并含 @internal。术语需与 kind 属性一致:'schema' 对应“Creates a ... schema.”,'validation' 对应“Creates a ... validation action.”,'transformation' 对应“Creates a ... transformation action.”。统一使用 schema、action、issue、dataset、config 等术语。
限制:资料仅给出文档写作规范,未提供安装命令、运行方式、收费信息、支持平台或效果数据,这些暂未提供。