JSDoc 标签大全｜70+ 官方标签速查表

JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。

JSDoc 速通手册
——编程狮（w3cschool.cn）为前端新手量身打造的“一行一用”速查表

看完就能写注释，写完就能出文档！

1 起手式：一条万能模板

/**
 * @file  文件描述
 * @author 编程狮 <dev@w3cschool.cn>
 * @license MIT
 * @since   2025-08-06
 * @version 1.0.0
 */

2 常用标签「一行一用」

3 完整函数示例（复制即用）

/**
 * 获取用户详情
 * @func
 * @param {string} id - 用户ID
 * @param {object} [options] - 可选配置
 * @param {boolean} [options.cache=true] - 是否缓存
 * @returns {Promise<User>} 用户实例
 * @throws {Error} 当网络异常
 * @example
 * getUser('123').then(console.log);
 */
async function getUser(id, { cache = true } = {}) {
  if (!id) throw new Error('id 不能为空');
  return fetch(`/api/user/${id}?cache=${cache}`).then(r => r.json());
}

4 一键生成文档

1. 安装

   npm i -D jsdoc

2. 配置 jsdoc.json

   {
    "source": { "include": ["src"] },
    "opts": { "destination": "docs" }
   }

3. 运行

   npx jsdoc -c jsdoc.json

4. 打开 docs/index.html 查看效果。

5 速背口诀

“变量加 @type，函数加 @param，返回加 @returns，枚举用 @enum，弃用 @deprecated 别忘写！”

6 JSDoc 3 全部标签速查表（共 70+）

按使用频率分 4 级：

⭐⭐⭐ 必背（蓝框） ⭐⭐ 常用（绿框） ⭐ 进阶（灰框） ◦ 其他（了解）

① 文件级

② 类型与变量

③ 函数 / 方法

④ 类 / 模块 / 命名空间

⑤ 成员可见性

⑥ 事件与监听

⑦ 其他实用标签

⑧ 模板与泛型

⑨ 完整模板速用

/**
 * @file 用户模块
 * @author 编程狮 <dev@w3cschool.cn>
 * @since 1.0.0
 */


/**
 * @typedef {Object} User
 * @property {string} name  用户名
 * @property {number} age   年龄
 */


/**
 * 创建用户
 * @func
 * @param {User} user
 * @returns {Promise<User>}
 * @throws {Error} 参数非法
 * @example
 * createUser({name:'Tom',age:18})
 */
async function createUser(user) { ... }