JSDoc 常用标签 #

标签概述 #

JSDoc 提供了丰富的标签用于描述代码的不同方面。标签以 @ 符号开头，用于标识注释中的特定信息。

text 
┌─────────────────────────────────────────────────────────────┐
│                     JSDoc 标签分类                           │
├─────────────────────────────────────────────────────────────┤
│  描述标签：描述代码的功能和行为                                │
│  类型标签：定义变量、参数、返回值的类型                        │
│  作用域标签：定义代码的作用域和可见性                          │
│  继承标签：描述类之间的继承关系                                │
│  元数据标签：提供额外的元数据信息                              │
└─────────────────────────────────────────────────────────────┘

描述标签 #

@description 描述标签 #

添加详细描述：

javascript 
/**
 * @description 计算两个数字的和
 * 该函数接受两个数字参数，返回它们的和。
 */
function add(a, b) {
  return a + b;
}

// 简写：描述文本直接写在注释开头
/**
 * 计算两个数字的和
 * 该函数接受两个数字参数，返回它们的和。
 */
function add(a, b) {
  return a + b;
}

@summary 摘要标签 #

添加简短摘要：

javascript 
/**
 * @summary 计算两数之和
 * @description 该函数接受两个数字参数，返回它们的和。
 * 支持整数和浮点数运算。
 */
function add(a, b) {
  return a + b;
}

@example 示例标签 #

添加使用示例：

javascript 
/**
 * 格式化日期
 * @param {Date} date - 日期对象
 * @param {string} format - 格式字符串
 * @returns {string} 格式化后的字符串
 * @example
 * // 基本用法
 * formatDate(new Date(), 'YYYY-MM-DD')
 * // 返回 '2024-01-15'
 * 
 * @example
 * // 包含时间
 * formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
 * // 返回 '2024-01-15 10:30:00'
 */
function formatDate(date, format) {
  // ...
}

@see 参考标签 #

添加参考链接：

javascript 
/**
 * 发送 HTTP 请求
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch API}
 * @see {@link request} 相关方法
 * @see module:utils/http
 */
function fetch(url) {
  // ...
}

@deprecated 废弃标签 #

标记已废弃的代码：

javascript 
/**
 * @deprecated 自版本 2.0 起废弃，请使用 newMethod
 * @see newMethod
 */
function oldMethod() {
  // ...
}

/**
 * @deprecated 使用 {@link newMethod} 代替
 */
function anotherOldMethod() {
  // ...
}

@since 版本标签 #

标记添加版本：

javascript 
/**
 * @since 1.0.0
 */
function feature() {
  // ...
}

/**
 * @since 2.1.0
 */
function newFeature() {
  // ...
}

类型标签 #

@type 类型标签 #

定义变量类型：

javascript 
/**
 * @type {string}
 */
let name = 'John';

/**
 * @type {number[]}
 */
let scores = [90, 85, 95];

/**
 * @type {Object<string, number>}
 */
let config = { timeout: 5000 };

/**
 * @type {User | null}
 */
let currentUser = null;

@param 参数标签 #

描述函数参数：

javascript 
// 基本用法
/**
 * @param {string} name - 用户名
 */
function greet(name) {}

// 可选参数
/**
 * @param {string} name - 用户名
 * @param {number} [age] - 年龄（可选）
 */
function createUser(name, age) {}

// 默认值
/**
 * @param {string} [name='Guest'] - 用户名
 */
function greet(name = 'Guest') {}

// 对象参数属性
/**
 * @param {Object} user - 用户对象
 * @param {string} user.name - 用户名
 * @param {number} user.age - 年龄
 */
function saveUser(user) {}

// 解构参数
/**
 * @param {Object} options - 配置选项
 * @param {string} options.url - 请求地址
 * @param {string} [options.method='GET'] - 请求方法
 */
function request({ url, method = 'GET' }) {}

// 剩余参数
/**
 * @param {...number} numbers - 数字列表
 */
function sum(...numbers) {}

@returns 返回值标签 #

描述返回值：

javascript 
// 基本用法
/**
 * @returns {number} 两数之和
 */
function add(a, b) {
  return a + b;
}

// 无返回值
/**
 * @returns {void}
 */
function log(message) {
  console.log(message);
}

// Promise 返回
/**
 * @returns {Promise<User>} 用户 Promise
 */
async function fetchUser() {
  // ...
}

// 复杂返回类型
/**
 * @returns {{ name: string, age: number }} 用户信息
 */
function getUser() {
  return { name: 'John', age: 25 };
}

@throws 异常标签 #

描述可能抛出的异常：

javascript 
/**
 * @throws {Error} 当除数为零时抛出
 */
function divide(a, b) {
  if (b === 0) {
    throw new Error('Division by zero');
  }
  return a / b;
}

/**
 * @throws {TypeError} 参数类型错误
 * @throws {RangeError} 参数超出范围
 */
function setAge(age) {
  if (typeof age !== 'number') {
    throw new TypeError('Age must be a number');
  }
  if (age < 0 || age > 150) {
    throw new RangeError('Invalid age');
  }
}

@typedef 类型定义标签 #

定义类型别名：

javascript 
/**
 * 用户类型
 * @typedef {Object} User
 * @property {number} id - 用户 ID
 * @property {string} name - 用户名
 * @property {string} email - 邮箱
 * @property {string[]} [roles] - 角色列表
 */

/**
 * @param {User} user - 用户对象
 */
function saveUser(user) {}

@property 属性标签 #

定义对象属性：

javascript 
/**
 * 配置对象
 * @typedef {Object} Config
 * @property {string} baseURL - 基础地址
 * @property {number} [timeout=5000] - 超时时间
 * @property {Object} [headers] - 请求头
 */

/**
 * @type {Config}
 */
const config = {
  baseURL: '/api',
  timeout: 5000
};

@callback 回调标签 #

定义回调类型：

javascript 
/**
 * 请求回调函数
 * @callback RequestCallback
 * @param {Error|null} error - 错误对象
 * @param {Object} [data] - 响应数据
 * @returns {void}
 */

/**
 * 发送请求
 * @param {string} url - 请求地址
 * @param {RequestCallback} callback - 回调函数
 */
function request(url, callback) {}

@template 泛型标签 #

定义泛型类型：

javascript 
/**
 * @template T
 * @param {T} value - 输入值
 * @returns {T} 返回相同类型
 */
function identity(value) {
  return value;
}

/**
 * @template T, U
 * @param {T} first - 第一个值
 * @param {U} second - 第二个值
 * @returns {{ first: T, second: U }}
 */
function pair(first, second) {
  return { first, second };
}

/**
 * @template {Object} T - 必须是对象类型
 * @param {T} obj - 对象参数
 */
function process(obj) {}

类和模块标签 #

@class 类标签 #

定义类：

javascript 
/**
 * 用户类
 * @class
 * @classdesc 表示系统中的用户
 */
class User {
  // ...
}

/**
 * @classdesc 类的详细描述
 * 可以包含多行文本。
 */
class Config {
  // ...
}

@constructor 构造函数标签 #

标记构造函数：

javascript 
/**
 * 用户类
 * @class
 */
function User(name) {
  /**
   * @constructor
   */
  this.name = name;
}

// ES6 类
class Person {
  /**
   * @constructor
   * @param {string} name - 用户名
   */
  constructor(name) {
    this.name = name;
  }
}

@extends 继承标签 #

描述继承关系：

javascript 
/**
 * 管理员用户
 * @class
 * @extends User
 */
class Admin extends User {
  // ...
}

/**
 * @extends {EventEmitter}
 */
class MyEmitter extends EventEmitter {
  // ...
}

@implements 实现标签 #

描述接口实现：

javascript 
/**
 * @implements {IUserService}
 */
class UserService {
  // ...
}

@interface 接口标签 #

定义接口：

javascript 
/**
 * 用户服务接口
 * @interface IUserService
 */

/**
 * 获取用户
 * @function
 * @name IUserService#getUser
 * @param {number} id - 用户 ID
 * @returns {Promise<User>}
 */

/**
 * 保存用户
 * @function
 * @name IUserService#saveUser
 * @param {User} user - 用户对象
 * @returns {Promise<void>}
 */

@module 模块标签 #

定义模块：

javascript 
/**
 * HTTP 工具模块
 * @module utils/http
 */

/**
 * 用户服务模块
 * @module UserService
 */

@namespace 命名空间标签 #

定义命名空间：

javascript 
/**
 * 工具函数集合
 * @namespace
 */
const Utils = {
  /**
   * 格式化日期
   * @memberof Utils
   * @param {Date} date - 日期对象
   * @returns {string}
   */
  formatDate(date) {
    // ...
  }
};

@memberof 成员标签 #

指定所属对象：

javascript 
/**
 * @namespace Services
 */

/**
 * 获取用户
 * @function
 * @memberof Services
 * @param {number} id - 用户 ID
 * @returns {User}
 */
function getUser(id) {
  // ...
}

作用域标签 #

@public 公有标签 #

标记公有成员：

javascript 
class User {
  /**
   * 用户名
   * @public
   * @type {string}
   */
  name;
}

@private 私有标签 #

标记私有成员：

javascript 
class User {
  /**
   * 内部 ID
   * @private
   * @type {string}
   */
  #id;

  /**
   * @private
   */
  _internalMethod() {}
}

@protected 保护标签 #

标记保护成员：

javascript 
class User {
  /**
   * @protected
   * @type {string}
   */
  _email;
}

@static 静态标签 #

标记静态成员：

javascript 
class User {
  /**
   * 默认角色
   * @static
   * @type {string}
   */
  static DEFAULT_ROLE = 'user';

  /**
   * 创建用户
   * @static
   * @param {Object} data - 用户数据
   * @returns {User}
   */
  static create(data) {
    return new User(data);
  }
}

@instance 实例标签 #

标记实例成员：

javascript 
/**
 * @class
 */
function User() {
  /**
   * @instance
   * @type {string}
   */
  this.name = 'John';
}

@inner 内部标签 #

标记内部成员：

javascript 
/**
 * @module utils
 */

/**
 * 内部辅助函数
 * @inner
 * @param {string} str - 输入字符串
 * @returns {string}
 */
function helper(str) {
  // ...
}

@global 全局标签 #

标记全局成员：

javascript 
/**
 * 全局配置
 * @global
 * @type {Object}
 */
var CONFIG = {};

功能标签 #

@function 函数标签 #

显式标记函数：

javascript 
/**
 * 处理函数
 * @function
 * @param {string} input - 输入
 * @returns {string}
 */
const handler = (input) => input;

/**
 * @function myFunction
 */
const myFunction = function() {};

@method 方法标签 #

标记方法：

javascript 
class User {
  /**
   * 获取用户名
   * @method
   * @returns {string}
   */
  getName() {
    return this.name;
  }
}

@constant 常量标签 #

标记常量：

javascript 
/**
 * API 基础地址
 * @constant {string}
 */
const API_BASE_URL = 'https://api.example.com';

/**
 * @const
 * @type {number}
 */
const MAX_RETRIES = 3;

@readonly 只读标签 #

标记只读：

javascript 
class User {
  /**
   * 用户 ID
   * @type {string}
   * @readonly
   */
  id;
}

/**
 * @type {string}
 * @readonly
 */
const VERSION = '1.0.0';

@enum 枚举标签 #

定义枚举：

javascript 
/**
 * 用户状态枚举
 * @enum {string}
 * @readonly
 */
const Status = {
  /** 活跃 */
  ACTIVE: 'active',
  /** 未激活 */
  INACTIVE: 'inactive',
  /** 已禁用 */
  DISABLED: 'disabled'
};

/**
 * @enum {number}
 */
const HttpStatus = {
  OK: 200,
  NOT_FOUND: 404,
  SERVER_ERROR: 500
};

@default 默认值标签 #

标记默认值：

javascript 
/**
 * 超时时间
 * @type {number}
 * @default 5000
 */
let timeout = 5000;

/**
 * @param {string} [name='Guest'] - 用户名
 * @default 'Guest'
 */
function greet(name = 'Guest') {}

@fires 事件标签 #

描述触发的事件：

javascript 
/**
 * 用户登录
 * @fires User#login
 * @fires User#sessionStart
 */
function login(credentials) {
  // ...
  this.emit('login', user);
}

@listens 监听标签 #

描述监听的事件：

javascript 
/**
 * @listens User#login
 * @listens User#logout
 */
function initUserHandlers() {
  user.on('login', handleLogin);
  user.on('logout', handleLogout);
}

@event 事件标签 #

定义事件：

javascript 
/**
 * 登录事件
 * @event User#login
 * @type {Object}
 * @property {User} user - 用户对象
 * @property {Date} timestamp - 时间戳
 */

/**
 * @fires User#login
 */
function login() {
  /**
   * @event User#login
   */
  this.emit('login', { user, timestamp: new Date() });
}

其他标签 #

@author 作者标签 #

标记作者：

javascript 
/**
 * @author John Doe <john@example.com>
 * @author Jane Doe <jane@example.com>
 */
function myFunction() {}

@license 许可证标签 #

标记许可证：

javascript 
/**
 * @license MIT
 */
// 或
/**
 * @license
 * Copyright (c) 2024 John Doe
 * MIT License
 */

@version 版本标签 #

标记版本：

javascript 
/**
 * @version 1.0.0
 */
function myFunction() {}

/**
 * @version 2.0.0
 * @since 1.0.0
 */
class MyClass {}

@ignore 忽略标签 #

忽略文档生成：

javascript 
/**
 * @ignore
 */
function internalHelper() {}

/**
 * @private
 * @ignore
 */
function _privateMethod() {}

@todo 待办标签 #

标记待办事项：

javascript 
/**
 * @todo 添加参数验证
 * @todo 支持异步操作
 */
function processData(data) {}

@override 重写标签 #

标记重写方法：

javascript 
class User {
  /**
   * @override
   */
  toString() {
    return `User: ${this.name}`;
  }
}

@abstract 抽象标签 #

标记抽象方法：

javascript 
class BaseUser {
  /**
   * 获取用户类型
   * @abstract
   * @returns {string}
   */
  getType() {
    throw new Error('Must implement getType()');
  }
}

@virtual 虚拟标签 #

同 @abstract：

javascript 
/**
 * @virtual
 */
function mustImplement() {}

@external 外部标签 #

引用外部资源：

javascript 
/**
 * @external JSON
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON|JSON}
 */

/**
 * 解析 JSON
 * @function
 * @see {@link external:JSON.parse}
 */

标签组合使用 #

完整函数文档 #

javascript 
/**
 * 发送 HTTP 请求
 * 
 * @description 发送一个 HTTP 请求并返回响应数据
 * @param {string} url - 请求地址
 * @param {Object} [options] - 请求选项
 * @param {string} [options.method='GET'] - 请求方法
 * @param {Object} [options.headers] - 请求头
 * @param {*} [options.body] - 请求体
 * @param {number} [options.timeout=5000] - 超时时间
 * @returns {Promise<Response>} 响应 Promise
 * @throws {NetworkError} 网络错误时抛出
 * @throws {TimeoutError} 请求超时时抛出
 * @example
 * // GET 请求
 * request('/api/users')
 *   .then(data => console.log(data))
 * 
 * @example
 * // POST 请求
 * request('/api/users', {
 *   method: 'POST',
 *   body: { name: 'John' }
 * })
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch API}
 * @since 1.0.0
 */
async function request(url, options = {}) {
  // ...
}

完整类文档 #

javascript 
/**
 * 用户管理类
 * 
 * @class
 * @classdesc 提供用户的增删改查功能
 * @extends EventEmitter
 * @fires User#created
 * @fires User#updated
 * @fires User#deleted
 * 
 * @example
 * const userManager = new UserManager();
 * const user = await userManager.create({ name: 'John' });
 */
class UserManager extends EventEmitter {
  /**
   * 创建 UserManager 实例
   * @constructor
   * @param {Object} [config] - 配置选项
   * @param {string} [config.apiBase='/api'] - API 基础地址
   */
  constructor(config = {}) {
    super();
    /**
     * API 基础地址
     * @type {string}
     * @readonly
     */
    this.apiBase = config.apiBase || '/api';
    
    /**
     * 用户缓存
     * @private
     * @type {Map<number, User>}
     */
    this._cache = new Map();
  }

  /**
   * 创建用户
   * @public
   * @param {Object} data - 用户数据
   * @returns {Promise<User>} 用户实例
   * @fires User#created
   * @since 1.0.0
   */
  async create(data) {
    // ...
  }

  /**
   * 获取默认角色
   * @static
   * @returns {string} 默认角色
   */
  static getDefaultRole() {
    return 'user';
  }
}

标签速查表 #

标签 用途 示例
@param 参数描述 @param {string} name - 用户名
@returns 返回值描述 @returns {number} 总和
@type 变量类型 @type {string}
@typedef 类型别名 @typedef {Object} User
@property 对象属性 @property {string} name
@class 类定义 @class
@extends 继承关系 @extends User
@module 模块定义 @module utils
@example 使用示例 @example fn()
@throws 异常描述 @throws {Error}
@deprecated 废弃标记 @deprecated 使用 newFn
@see 参考链接 @see {@link url}
@private 私有成员 @private
@static 静态成员 @static
@readonly 只读属性 @readonly
@default 默认值 @default 0
@enum 枚举定义 @enum {string}
@template 泛型定义 @template T
@callback 回调类型 @callback Handler

下一步 #

现在你已经掌握了 JSDoc 常用标签，接下来学习 高级用法 了解更多高级技巧！

最后更新：2026-03-29