JavaScript函数注释标准写法：JSDoc常用标签与语法详解

一、JSDoc 注释基础语法与解析机制

在 JavaScript 中，只有以双星号开头的块级注释 /** ... */ 才会被现代代码编辑器（如 VS Code、WebStorm）及自动化文档工具解析为 JSDoc。单行注释 // 与普通的块级注释 /* ... */ 仅作为解释性文字存在，不会参与任何类型推断或智能提示生成。

一个标准的 JSDoc 函数注释块通常包含三个逻辑区域：顶部是函数的功能描述，中间是按参数出现顺序排列的 @param 标签集合，底部则是 @returns 返回值声明，以及可选的 @throws 异常声明与 @example 代码示例。

/**
 * 发送 HTTP 请求并解析返回的 JSON 数据
 * 内部集成身份鉴权头注入与超时取消控制器
 *
 * @param {string} url - 请求的目标 URL 地址
 * @param {Object} [options] - 请求可选配置项
 * @param {number} [options.timeout=5000] - 超时毫秒数，默认 5000ms
 * @returns {Promise<ApiResponse>} 解析后的业务数据包
 * @throws {NetworkError} 网络中断或服务不可用时抛出
 */
async function fetchJson(url, options = {}) {
  // 具体逻辑实现
}

当光标悬停在调用该函数的代码处时，IDE 会读取上述元数据，将其渲染为结构化的悬浮提示框（Hover Tooltip）。这使调用者在无需翻阅底层源码的情况下，即可直观确认每个形参的类型、默认值以及可能触发的错误。

二、核心函数标签与常用语法规则

函数注释的质量取决于标签选择的准确度与类型表达的精细度。以下是函数编写过程中最高频使用的四类核心标签及其语法规则。

1. @param：参数声明与多维修饰

@param 标签用于声明函数接收的形参。基础语法为 @param {Type} name - description，其中连字符 - 可选，但加入后能更清晰地区分参数名与解释文字。

• 原生标量类型：使用小写形式 {string}、{number}、{boolean}、{symbol}、{bigint}。切勿使用大写包装对象（如 String 或 Number），因为包装对象与原始值的类型行为存在本质差异。
• 联合类型（Union Types）：使用管道符 | 连接多种可能类型，例如 {string|number} 表示参数既可传入字符串也可传入数值。
• 可选参数与默认值：使用方括号包裹参数名声明可选。若存在默认值，可在等号后注明，例如 @param {number} [limit=10]。
• 对象属性展开：当形参是一个配置对象时，建议通过点语法逐层标注内部属性，例如 @param {string} config.url 与 @param {number} [config.timeout]。
• 剩余参数（Rest Parameters）：在类型花括号内添加三个点，例如 @param {...number} values - 参与求和的一组数字。

2. @returns：返回值声明

@returns（也可缩写为 @return）用于明确函数的输出类型与业务含义。语法格式为 @returns {Type} description。

如果函数没有返回值（或仅隐式返回 undefined），应显式标记为 {void}；对于异步函数（async function），由于 JavaScript 底层始终将其包装为期约对象，因此返回值类型必须用泛型包裹，例如 @returns {Promise<UserInfo>}，避免单纯标注为 {UserInfo} 导致调用方误以为能同步获取结果。

3. @throws：异常类型与触发边界

@throws（同义标签为 @exception）用于说明函数在何种边界条件下会主动抛出错误。这一声明在编写公共工具库或关键业务逻辑时尤为重要，它能提醒调用方做好 try...catch 防御处理。

/**
 * 校验用户输入的手机号合法性
 *
 * @param {string} phone - 待校验的手机号码
 * @returns {boolean} 校验通过返回 true
 * @throws {TypeError} 当 phone 传入非字符串类型时抛出
 * @throws {RangeError} 当字符串长度不等于 11 位时抛出
 */
function validatePhoneNumber(phone) {
  if (typeof phone !== 'string') {
    throw new TypeError('手机号入参必须为字符串');
  }
  if (phone.length !== 11) {
    throw new RangeError('手机号码长度必须为11位');
  }
  return /^1[3-9]\d{9}$/.test(phone);
}

4. @example：调用示例与典型用例

@example 标签用于在文档中展示具体用法。编辑器在渲染悬浮提示时，会对 @example 块内的代码进行语法高亮展示。编写示例时应尽量贴近实际业务场景，并附带预期的输出结果。

三、复杂数据结构声明：@typedef 与 @callback

在实际项目开发中，很多函数接收或返回的数据结构包含大量嵌套字段。如果直接在每个函数的 @param 或 @returns 中内联展开这些属性，注释将变得冗长杂乱，且相同的结构无法复用。为此，JSDoc 提供了 @typedef 与 @callback 标签。

1. @typedef 与 @property：构建工程化自定义类型

@typedef 用于定义一个命名的自定义类型别名，配合 @property 标签可以完整描述一个对象的属性规格：

/**
 * 用户核心信息数据模型
 * @typedef {Object} UserProfile
 * @property {number} id - 用户唯一数据库主键
 * @property {string} username - 登录账号名称
 * @property {string} [nickname] - 用户展示昵称（可选）
 * @property {'active' | 'suspended' | 'deleted'} status - 账户状态枚举
 * @property {Date} createdAt - 注册创建时间戳
 */

/**
 * 根据 ID 更新指定用户的基础资料
 * @param {number} userId - 目标用户ID
 * @param {Partial<UserProfile>} patchData - 需要局部更新的字段集
 * @returns {Promise<UserProfile>} 更新后的完整用户对象
 */
async function updateUserProfile(userId, patchData) {
  // 实现逻辑
}

将通用的 @typedef 声明集中放置在模块顶部或独立的类型定义文件（如 types.js）中，整个项目的所有函数都能直接引用 UserProfile 作为参数或返回值类型，彻底解决重复定义的问题。

2. @callback：声明高阶函数的回调签名

当函数入参包含回调函数（如事件监听器、异步观察者或数组处理函数）时，使用 @callback 可以精确约定回调函数接收的入参与期望的返回值：

/**
 * 数据变更事件通知回调
 * @callback DataChangeObserver
 * @param {string} field - 发生变更的属性键名
 * @param {*} oldValue - 变更前的值
 * @param {*} newValue - 变更后的新值
 * @returns {void}
 */

/**
 * 注册全局数据状态观察者
 * @param {string} scope - 观察的作用域模块
 * @param {DataChangeObserver} observer - 状态变更触发的监听回调
 */
function observeState(scope, observer) {
  // 注册监听器
}

四、规范编写 JSDoc 的标准操作流程

编写规范的 JSDoc 注释不应是开发完成后的被动补写，而应融入日常编码流程。遵循以下五个步骤，可以实现高效、无痛的注释编写与闭环校验。

五、常用修饰标签与工程化避坑指南

除了常规的类型标签外，JSDoc 还提供了一系列修饰性标签，用于在团队协作与库维护中传递架构层面的设计意图。

1. 常用修饰标签

• @deprecated：标记该函数已被弃用，并提供替代函数或迁移指引。编辑器通常会在调用废弃函数时渲染中划线删除效果。
• @see 与 @link：建立文档交叉引用。例如 @see {@link calculateTotal} 参阅结算算法实现。
• @readonly：标记属性为只读，禁止外部代码重新赋值。
• @async：显式标明异步操作，提示调用方应当使用 await 或 .then() 进行处理。
• @template T：声明泛型类型占位符，适用于封装通用工具函数（如深度克隆、分页切片或事件总线）。

2. 常见反模式与避坑要点

1. 杜绝无效注释：避免写出仅重复变量名的废话，例如 @param {string} name - 名字。有价值的注释应当解释该参数的格式约束、取值边界或业务含义，例如 @param {string} name - 用户真实姓名，长度 2~20 位，不允许包含特殊符号。
2. 保持注释与源码同步：在重构、增删形参或变更返回值逻辑时，必须第一优先级同步更新 JSDoc。包含错误类型的注释比完全不写注释更具破坏性，它会直接诱导 IDE 发出错误的自动补全建议。
3. 正确处理可选属性与默认值：当代码中使用了 ES6 默认参数（如 function sum(a, b = 0)）时，JSDoc 的方括号标注 @param {number} [b=0] 应与代码保持完全一致。
4. 善用自动化 Lint 规则：推荐在工程中引入 eslint-plugin-jsdoc，配置诸如 jsdoc/require-param、jsdoc/check-types 等规则，将注释合规性纳入 CI/CD 流水线，实现团队层面的规范落地。