UD5工具箱
常见问题
什么是 JSDoc？为什么要使用 JSDoc？
JSDoc 是 JavaScript 社区广泛使用的文档注释标准，使用特定格式的注释来描述代码的功能、参数和返回值。使用 JSDoc 的好处包括：IDE 可以根据 JSDoc 提供代码补全、类型提示和参数检查，提升开发效率；可以使用 JSDoc 工具自动生成 API 文档，节省手动编写文档的时间；团队协作时，JSDoc 注释帮助其他开发者快速理解代码的功能和用法；对于开源项目，JSDoc 注释是生成高质量 API 文档的基础。JSDoc 注释是一种低成本高回报的编码实践。
箭头函数如何添加 JSDoc 注释？
箭头函数的 JSDoc 注释格式与普通函数相同，注释放在函数定义的上方。对于 const 声明的箭头函数，注释放在 const 语句上方；对于作为属性的箭头函数，注释放在属性上方。示例：/** * 将两个数字相加 * @param {number} a - 第一个数字 * @param {number} b - 第二个数字 * @returns {number} 两数之和 */const add = (a, b) => a + b;。箭头函数的 JSDoc 同样使用 @param 和 @returns 标签描述参数和返回值。本工具支持直接输入箭头函数代码并自动生成 JSDoc 注释。
@param 标签中的类型有哪些常用写法？
@param 标签中的类型使用花括号包裹，常用写法包括：基本类型 - string、number、boolean、null、undefined；对象类型 - Object 或使用具体的接口名如 User；数组类型 - Array 或 string[]；函数类型 - function 或 Function；Promise - Promise<类型>；联合类型 - string | number；可选参数 - @param {string} [name]；带默认值 - @param {string} [name=World]；任意类型 - *；DOM 元素 - HTMLElement。对于复杂的类型结构，可以使用 @typedef 定义自定义类型，然后在 @param 中引用。正确的类型标注可以让 IDE 提供更精确的代码补全和类型检查。
异步函数的 JSDoc 应该如何描述返回值？
异步函数（async function）始终返回 Promise 对象，因此 JSDoc 的 @returns 标签应该描述 Promise 的解析值类型，而不是 Promise 本身。正确的写法是 @returns {Promise<UserData>} 用户数据，而不是 @returns {Promise}。这告诉 IDE 和开发者，当使用 await 等待这个函数时，得到的结果是 UserData 类型。如果异步函数可能返回 null，可以写为 @returns {Promise<UserData | null>} 用户数据或 null。如果异步函数没有有用的返回值，可以写为 @returns {Promise<void>}。正确的 Promise 类型描述对于 TypeScript 项目尤其重要。
TypeScript 函数还需要写 JSDoc 吗？
TypeScript 的类型系统本身提供了参数和返回值的类型信息，因此基本的类型描述可以省略。但 JSDoc 在 TypeScript 项目中仍然有价值：JSDoc 可以提供 TypeScript 类型无法表达的语义信息，如参数的业务含义、使用约束、副作用等；JSDoc 的 @example 标签可以提供使用示例，TypeScript 没有等效功能；JSDoc 的 @deprecated、@since、@author 等元数据标签在 TypeScript 中没有对应语法；对于通过 JSDoc 生成外部 API 文档的场景（如使用 TypeDoc），JSDoc 注释是必要的。因此，建议在 TypeScript 项目中使用 JSDoc 补充类型系统无法表达的信息。
生成的 JSDoc 可以直接使用吗？
本工具生成的 JSDoc 注释基于函数代码的结构分析和类型推断，对于简单函数通常可以直接使用。但对于复杂函数，建议在使用前进行以下检查：验证参数类型是否准确，特别是对于联合类型和复杂对象类型；检查描述是否清晰且准确反映函数的功能；确认返回值类型是否正确，特别是对于异步函数和条件返回；如果启用了 @author、@example、@since 标签，检查内容是否合适。生成的注释是一个很好的起点，可以大幅减少手动编写的工作量。建议将生成的注释作为初稿，根据实际情况进行必要的调整和完善。
如何让工具更准确地推断参数类型？
提高类型推断准确率的方法包括：使用描述性的参数名，如 userName 而不是 u，itemCount 而不是 n，isActive 而不是 a。参数名中的关键词（如 name、count、is、has、list 等）是类型推断的重要依据。对于函数类型的参数，使用 callback、handler、fn 等命名。对于 DOM 元素参数，使用 element、el、node 等命名。对于复杂类型，建议使用 TypeScript 类型注解来明确类型，工具会直接使用注解的类型信息。在函数体中包含返回语句也有助于返回值类型的推断。