JSDoc是JavaScript的文档注释标准，通过@param、@returns等标签描述函数参数、返回值类型及功能，提升代码可读性和IDE智能提示，常用于现代前端开发中辅助类型检查与协作。
JS注解并不是JavaScript语言本身的特性，不像Java有@Deprecated这样的原生注解支持。但在现代前端开发中，我们通常所说的“JS注解”其实是通过JSDoc这种文档注释语法来实现的，用于描述函数、参数、返回值等信息，提升代码可读性和工具支持（如IDE智能提示、类型检查）。
什么是JSDoc注解
JSDoc是一种广泛使用的JavaScript文档标准，它使用特定格式的多行注释来为函数、变量、类等添加元信息。这些注解能被工具（如VS Code、WebStorm、TypeScript、ESLint）识别，帮助开发者理解代码。
基本结构如下：
/** * 函数说明 * @param {类型} 参数名 - 参数描述 * @returns {类型} 返回值描述 */常见JSDoc标签在函数中的使用
以下是一些常用的JSDoc标签及其在函数上的应用示例：
- @param：描述函数参数的类型和含义
- @returns 或 @return：描述返回值
- @description：补充函数功能说明
- @example：提供使用示例
- @throws：说明可能抛出的异常
- @deprecated：标记函数已废弃
实际使用示例
下面是一个带完整JSDoc注解的函数示例：
/**
- 计算两个数的和
- @param {number} a - 第一个加数
- @param {number} b - 第二个加数
- @returns {number} 两数相加的结果
- @example
- add(2, 3) // 返回 5 */ function add(a, b) { return a + b; }
另一个更复杂的例子，包含类型对象和异常说明：
/**
- 获取用户基本信息
- @param {Object} user - 用户对象
- @param {string} user.name - 用户姓名
- @param {number} user.age - 用户年龄
- @throws {Error} 当用户姓名为空时抛出错误
- @returns {string} 格式化的用户信息
*/
function getUserInfo(user) {
if (!user.name) {
throw new Error('Name is required');
}
return
${user.name} is ${user.age} years old.; }
配合TypeScript或工具使用效果更佳
如果你使用TypeScript，JSDoc可以与类型系统结合，在不写.ts文件的情况下提供类型提示。例如：
/**
- @typedef {Object} Config
- @property {string} url - 请求地址
- @property {number} timeout - 超时时间（毫秒） */
/**
- 发送请求
- @param {Config} config */ function request(config) { console.log(config.url); }
在VS Code中，调用request时就会有自动提示。
基本上就这些。JSDoc不是必须的，但合理使用能让团队协作更顺畅，代码更容易维护。不复杂但容易忽略。
