UD5工具箱
术语表
JSDoc
JSDoc 是 JavaScript 社区广泛使用的文档注释标准。它允许开发者在 JavaScript 代码中使用特定格式的注释来描述代码的结构、功能和用法。JSDoc 注释以三个斜杠加星号（/**）开头，包含各种标签来描述不同的信息。常用的 JSDoc 标签包括：@param 描述函数参数、@returns 描述返回值、@description 添加详细描述、@example 提供使用示例、@throws 描述可能的异常、@type 描述变量类型、@typedef 定义自定义类型、@callback 定义回调函数类型、@deprecated 标记已弃用、@since 标记引入版本、@author 标注作者。JSDoc 注释可以被 IDE 解析用于代码补全和类型提示，也可以被文档生成工具转换为 HTML 文档。
箭头函数
箭头函数是 ES6（ECMAScript 2015）引入的函数简写语法，使用箭头（=>）定义。它的语法比传统的 function 关键字更简洁。单行箭头函数可以省略花括号和 return 关键字：const add = (a, b) => a + b。多行箭头函数需要花括号包裹函数体：const add = (a, b) => { const sum = a + b; return sum; }。箭头函数与传统函数的重要区别是：箭头函数没有自己的 this，它继承外层作用域的 this；箭头函数没有 arguments 对象；箭头函数不能用作构造函数。在为箭头函数编写 JSDoc 时，通常使用 @param 和 @returns 标签。
异步函数（async/await）
异步函数是 ES2017 引入的处理异步操作的语法，使用 async 关键字定义函数，使用 await 关键字等待 Promise 的结果。async 函数始终返回一个 Promise 对象，即使函数体中没有显式使用 Promise。例如：async function fetchData(url) { const response = await fetch(url); return response.json(); }。异步函数的优势在于：将异步代码写成同步的形式，提高可读性；错误处理可以使用 try/catch 语法；避免了 Promise 链式调用的复杂性。在为异步函数编写 JSDoc 时，@returns 标签应该描述 Promise 的解析值类型，如 @returns {Promise<User>} 用户信息。
TypeScript
TypeScript 是 JavaScript 的超集，由 Microsoft 开发和维护。它在 JavaScript 的基础上添加了静态类型系统，允许开发者在代码中显式声明变量、参数和返回值的类型。TypeScript 的类型系统非常强大，支持基本类型（string、number、boolean）、复合类型（数组、元组、对象）、联合类型、交叉类型、泛型、类型别名、接口等。TypeScript 代码通过编译器（tsc）编译为纯 JavaScript 代码后才能运行。在 JSDoc 注释中，可以使用 TypeScript 的类型注解语法来提供更精确的类型信息，如 @param {string | number} id - 用户ID。
@param 标签
@param 是 JSDoc 中用于描述函数参数的标签。它的格式为 @param {类型} 参数名 - 描述，其中类型是可选的，参数名必须与函数定义中的参数名一致。可以添加可选性标记：@param {string} [name] - 可选参数；或添加默认值说明：@param {string} [name=World] - 带默认值的参数。对于有多个参数的函数，每个参数需要单独一行 @param 标签，顺序应与函数参数列表一致。@param 标签是 JSDoc 中最常用的标签之一，正确的参数描述有助于 IDE 提供准确的代码补全和类型提示。
@returns 标签
@returns（或 @return）是 JSDoc 中用于描述函数返回值的标签。它的格式为 @returns {类型} 描述。对于没有返回值的函数（void），可以省略 @returns 标签或写为 @returns {void}。对于返回 Promise 的异步函数，类型应该是 Promise 的解析值类型，如 @returns {Promise<UserData>} 用户数据。对于返回多种类型的函数，可以使用联合类型，如 @returns {string | number} 名称或ID。@returns 标签帮助 IDE 和文档生成工具了解函数的输出，是 JSDoc 注释中不可或缺的部分。
@example 标签
@example 标签用于在 JSDoc 注释中提供函数的使用示例。它的格式为 @example 后跟代码示例，代码示例通常使用代码围栏（三个反引号）包裹。一个好的使用示例应该：展示函数最常见的使用场景、包含输入参数和预期输出、演示函数的主要功能。例如：@example // 基本用法 const result = add(1, 2); // 返回 3 // 字符串拼接 const greeting = greet('World'); // 返回 'Hello, World!'。使用示例可以帮助其他开发者快速理解函数的用法，减少阅读文档的时间。
IDE 代码补全
IDE 代码补全是现代代码编辑器（如 VS Code、WebStorm、IntelliJ IDEA 等）提供的智能功能，它根据代码上下文自动建议变量名、函数名、方法名和参数。JSDoc 注释可以显著增强代码补全的功能：当函数有 JSDoc 注释时，IDE 可以在调用该函数时显示参数的名称、类型和描述；在编写代码时提供基于类型的自动补全建议；在鼠标悬停时显示详细的文档信息；在参数类型不匹配时给出警告。正确编写 JSDoc 注释是获得高质量代码补全的前提。
API 文档生成
API 文档生成是指使用工具将代码中的 JSDoc 注释自动转换为格式化的 HTML 文档的过程。最常用的工具是 JSDoc 本身（jsdoc 命令行工具），它会扫描代码中的 JSDoc 注释，生成包含函数列表、参数说明、返回值说明、使用示例等内容的 HTML 文档站点。其他文档生成工具包括：TypeDoc（专为 TypeScript 设计）、ESDoc（现代化的 JavaScript 文档生成器）、Documentation.js（支持多种注释格式）。这些工具都以 JSDoc 注释作为输入，生成结构清晰、便于浏览的 API 文档。
类型推断
类型推断是指根据代码的上下文信息自动判断变量、参数或返回值的数据类型的过程。在 JSDoc 生成场景中，类型推断根据参数名称、默认值、使用方式等信息猜测参数的类型。例如，参数名 count 通常暗示 number 类型，name 暗示 string 类型，isReady 暗示 boolean 类型。类型推断的准确率取决于命名约定和代码模式的规律性。对于 TypeScript 代码，类型信息是显式声明的，不需要推断。工具的类型推断功能作为基础参考，开发者可以在生成后手动调整类型信息以确保准确性。