UD5工具箱
使用教程
第一步：了解 JSDoc 注释格式
JSDoc 注释以三个斜杠加星号开头（/**），以星号加斜杠结尾（*/），中间是注释内容。注释内容以星号对齐，每个星号后有一个空格。常用的 JSDoc 标签包括：@description 用于添加详细描述；@param 用于描述参数，格式为 @param {类型} 参数名 - 描述；@returns 用于描述返回值，格式为 @returns {类型} 描述；@throws 用于描述可能抛出的异常，格式为 @throws {类型} 描述；@example 用于提供使用示例。了解这些基本格式有助于理解生成的注释内容。
第二步：输入函数代码
在左侧输入框中粘贴或输入你要添加 JSDoc 注释的 JavaScript 函数。工具支持多种函数类型的输入：简单函数声明（function add(a, b) { return a + b; }）、异步函数（async function fetchData(url) { ... }）、箭头函数（const multiply = (a, b) => a * b;）、类方法（class 中的方法定义）以及带有 TypeScript 类型注解的函数（function add(a: number, b: number): number { ... }）。确保输入的代码是完整的函数定义，包括函数名、参数列表和函数体。函数体中的代码不需要特别完整，但参数和返回语句应该清晰，以便工具正确推断类型。
第三步：选择可选标签
根据需要勾选可选标签。如果你需要标注函数的作者信息，勾选"添加 @author"复选框，并在出现的输入框中填写作者名称。如果你需要为函数添加使用示例，勾选"添加 @example"复选框。如果你需要标注函数的引入版本，勾选"添加 @since"复选框，并填写版本号。这些标签都是可选的，如果不勾选，生成的注释中不会包含这些标签。对于大多数情况，只需要基本的 @param 和 @returns 标签即可。
第四步：查看生成结果
输入代码后，右侧的预览区域会自动显示生成的 JSDoc 注释。检查注释内容是否准确：参数列表是否完整、类型推断是否正确、返回值类型是否匹配、描述是否清晰。如果发现类型推断不准确，可以回到输入框修改参数名称（使其更符合类型命名约定），或者在输入框中使用 TypeScript 类型注解来明确类型信息。调整完成后，预览会自动更新。
第五步：复制和使用
确认生成的 JSDoc 注释正确后，点击"复制"按钮将注释块复制到剪贴板。然后切换到你的代码编辑器，将光标定位到目标函数的上方（紧挨着函数定义的那一行），使用 Ctrl+V 粘贴注释。粘贴后，检查注释的缩进是否与代码风格一致，必要时进行调整。对于 TypeScript 项目，生成的 JSDoc 注释可以作为补充说明，但建议优先使用 TypeScript 的原生类型系统。
实用技巧
技巧一：使用有意义的参数名。参数名越具有描述性，工具推断的类型就越准确。例如，使用 userName 而不是 u，使用 itemCount 而不是 n。技巧二：对于复杂类型，使用 TypeScript 注解。当参数是联合类型、泛型或自定义类型时，TypeScript 注解比自动推断更准确。技巧三：保持函数体中包含返回语句。返回语句有助于工具推断返回值类型。技巧四：对于重载函数，分别输入每个重载签名生成对应的注释。技巧五：生成后手动检查和调整。自动工具不可能百分之百准确，生成后花几秒钟检查注释质量是值得的。