jsdoc-guide 是一份 JSDoc 编写指南,用于指导 AI 驱动的文档生成。其核心要求是:所有导出函数都必须包含四个强制标签,基本结构为 @description(一句话摘要)、@param {Type} name - 描述、@returns {Type} 描述以及 @example 示例代码。
在具体写法上,指南给出了若干核心模式。@description 的首行应是一句简洁的总结,例如“Debounces a value and returns it after the specified delay.”,而不是含糊的“Does something with a value.”。@param 需要同时给出类型和描述,支持可选参数(如 {number} [delay=300])以及配置对象(如 {Object} options)。@returns 用于描述返回值,既可写简单类型(如 {T} The debounced value.),也可写元组形式(如 {[boolean, () => void]} [state, toggle])。@example 则要求提供可运行的代码片段,例如基于 useState 和 useDebounce 的调用示例。
该指南还提供了 references 部分,其中 details.md 包含完整标签指南与复杂情况说明(具体内容暂未提供)。
适用场景包括:编写 JSDoc 注释、为函数补充文档、添加代码注释,尤其是需要让 AI 基于注释生成文档时。限制方面,资料未说明支持的编程语言范围、工具集成方式或校验机制,相关细节暂未提供。