JSDoc 文档注释完整指南

从基础语法到高级类型定义，掌握 JavaScript 文档注释的最佳实践

1.1 基本语法

JSDoc 注释必须以 /** 开头，以 */ 结尾。内部可以使用多行描述和一系列块标签（以 @ 开头）。

📄 基本语法模板

/** * 函数的简短描述（第一行会作为摘要） * * 可以添加更详细的说明，支持 **Markdown** 格式。 * - 支持列表 * - 支持 `代码` * * @param {参数类型} 参数名 - 参数描述 * @returns {返回值类型} 返回值描述 */

1.2 简单的函数注释

📄 加法函数示例

/** * 计算两个数字的和 * @param {number} a - 第一个数字 * @param {number} b - 第二个数字 * @returns {number} 两数之和 */functionadd(a, b){return a + b;}

2.1 参数相关标签

常用参数标签包括：

@param@param {类型}[可选参数][参数=默认值]...剩余参数参数名.属性名

📄 用户注册函数 - 完整参数演示

/** * 用户注册函数 * @param {string} username - 用户名（必填） * @param {string} email - 邮箱地址（必填） * @param {number} [age=18] - 年龄（可选，默认为18） * @param {...number} scores - 可变参数，多个分数 * @param {Object} options - 配置选项 * @param {boolean} options.verbose - 是否输出详细信息 */functionregister(username, email, age = 18, ...scores){  // 实现代码}

2.2 返回值标签

一个函数只能有一个@returns（或 @return），但可以使用内联类型或 @typedef 来描述复杂结构。

❌ 错误示例（多个 @returns）——工具会报错或解析异常

❌ 不推荐写法

// 不推荐！工具会报错或解析异常/** * @returns {Object} 用户信息对象 * @returns {string} returns.name - 用户名   // 错误写法 */

✅ 正确写法一：内联对象类型

✅ 内联对象类型

/** * 获取用户信息 * @param {string} userId - 用户ID * @returns {{ name: string, age: number }} 包含用户名和年龄的对象 */functiongetUserInfo(userId) {  return {    name: "张三",    age: 25,  };}

✅ 正确写法二：结合 @typedef（推荐）

✅ 使用 @typedef

/** * @typedef {Object} UserInfo * @property {string} name - 用户名 * @property {number} age - 年龄 *//** * 获取用户信息 * @param {string} userId - 用户ID * @returns {UserInfo} 用户信息对象 */functiongetUserInfo(userId){  return {    name: "张三",    age: 25,  };}

2.3 异常处理标签

使用 @throws 描述可能抛出的错误。

📄 fetchData 异常处理

/** * 从API获取数据 * @param {string} url - API地址 * @returns {Promise<Object>} 返回的JSON数据 * @throws {Error} 当网络请求失败时抛出错误 * @throws {TypeError} 当URL格式不正确时抛出类型错误 */async function fetchData(url) {    if (!url.startsWith('http')) {        throw new TypeError('URL格式不正确');    }    const response = await fetch(url);    if (!response.ok) {        throw new Error('网络请求失败');    }    return response.json();}

2.4 类型标签 ⭐ 重要补充

以下类型标签在大型项目中至关重要：

@type@typedef@property@callback@enum

@type 示例

📄 @type 用法

/** @type {string} */let userName;/** @type {number[]} */const scores = [95, 87, 76];/** @type {{ x: number, y: number }} */const point = { x: 10, y: 20 };

@typedef 与 @property 详细用法

📄 类型定义

/** * @typedef {Object} User * @property {string} id - 用户唯一标识 * @property {string} name - 用户名 * @property {number} age - 年龄 * @property {string[]} hobbies - 爱好列表 *//** * @typedef {'admin' | 'editor' | 'viewer'} UserRole - 用户角色枚举 */

@callback 定义回调签名

📄 回调类型

/** * 处理结果回调 * @callback processCallback * @param {Error|null} error - 错误对象，成功时为 null * @param {Object} result - 处理结果 *//** * 执行异步任务 * @param {string} taskId - 任务ID * @param {processCallback} callback - 完成后的回调 */functiondoTask(taskId, callback) {    // 完成后调用 callback(null, result) 或 callback(error)}

@enum 定义枚举值

📄 枚举定义

/** * 状态枚举 * @readonly * @enum {number} */const Status = {    PENDING: 0,    APPROVED: 1,    REJECTED: 2};

3.1 类型定义的复用

@typedef 定义的类型可以在整个项目中引用，提高可维护性。

📄 复用 ApiResponse 类型

/** * @typedef {Object} ApiResponse * @property {boolean} success - 请求是否成功 * @property {*} data - 响应数据 * @property {string} [message] - 可选的消息字段 */ /** * 获取用户列表 * @returns {Promise<ApiResponse>} API 响应结构 */async function getUsers() {    // ...}

3.2 联合类型与泛型

联合类型使用 | 分隔，泛型使用 @template 声明。

📄 泛型函数

/** * 身份函数：返回传入的值 * @template T * @param {T} value - 任意类型的值 * @returns {T} 与输入相同的值 */functionidentity(value) {    return value;}/** * 安全获取对象属性 * @template T, K extends keyof T * @param {T} obj - 源对象 * @param {K} key - 属性键 * @returns {T[K]} 属性值 */functiongetProperty(obj, key) {    return obj[key];}

3.3 类的文档注释

使用 @class、@constructor、@static 等标签。

📄 User 类

/** * 用户实体类 * @class */class User {    /**     * 创建用户实例     * @param {string} name - 用户名     * @param {number} age - 年龄     */    constructor(name, age) {        /**         * 用户名         * @type {string}         */        this.name = name;        /**         * 年龄         * @type {number}         */        this.age = age;    }    /**     * 获取格式化信息     * @returns {string} 格式化字符串     */    getInfo() {        return `${this.name} (${this.age}岁)`;    }    /**     * 静态方法：验证用户名合法性     * @static     * @param {string} name - 待验证的用户名     * @returns {boolean} 是否有效     */    static validateName(name) {        return name.length >= 2;    }}

4.1 模块注释（ES模块）

使用 @module 定义模块，配合 @exports 或直接在 export 语句上注释。

📄 数学工具模块

/** * 数学工具模块 * @module mathUtils */ /** * 计算阶乘 * @param {number} n - 非负整数 * @returns {number} n 的阶乘 */export function factorial(n) {    if (n <= 1) return 1;    return n * factorial(n - 1);}

4.2 命名空间（对象字面量）

使用 @namespace 和 @memberof。

📄 Utils 命名空间

/** * 工具函数集合 * @namespace Utils */const Utils = {    /**     * 日期格式化     * @memberof Utils     * @param {Date} date - 日期对象     * @returns {string} ISO 格式日期部分     */    formatDate(date) {        return date.toISOString().split('T')[0];    },    /**     * 深度克隆对象     * @memberof Utils     * @param {Object} obj - 要克隆的对象     * @returns {Object} 克隆后的新对象     */    deepClone(obj) {        return JSON.parse(JSON.stringify(obj));    }};

5.1 描述 this 上下文

📄 @this 标签

/** * 点击处理函数 * @this {HTMLElement} 触发事件的元素 * @param {MouseEvent} event - 鼠标事件对象 */function handleClick(event) {    console.log(this.id);}

5.2 标记废弃与链接

@deprecated@see@since

📄 废弃标记

/** * 旧版登录方法 * @deprecated 自 v2.0 起使用 {@link newLogin} 替代 * @param {string} user - 用户名 * @param {string} pass - 密码 * @returns {boolean} 登录结果 * @see newLogin */functionoldLogin(user, pass) {    // ...}

5.3 示例代码

使用 @example 可以嵌入示例，支持 Markdown 代码块。

📄 @example 标签

/** * 计算两个数相除的结果 * @param {number} dividend - 被除数 * @param {number} divisor - 除数 * @returns {number} 商 * @throws {Error} 除数为零时抛出错误 * @example * // 返回 2.5 * divide(5, 2); * * @example * // 抛出错误 * try { *   divide(5, 0); * } catch (e) { *   console.error(e.message); * } */function divide(dividend, divisor) {    if (divisor === 0) throw new Error('除数不能为零');    return dividend / divisor;}

5.4 其他实用标签

@author@version@license

📄 元信息标签

/** * @author 张三 <zhangsan@example.com> * @version 1.2.3 * @license MIT */

6.1 完整示例：用户服务

📄 UserService 完整示例

/** * 用户服务模块，提供用户相关的 CRUD 操作 * @module services/UserService *//** * 用户信息对象 * @typedef {Object} User * @property {string} id - 唯一ID * @property {string} name - 姓名 * @property {string} email - 邮箱 * @property {number} [age] - 年龄（可选） *//** * 用户服务类 * @class */class UserService {    /**     * 创建用户服务实例     * @param {string} apiBase - API 基础路径     */    constructor(apiBase) {        /** @type {string} */        this.apiBase = apiBase;    }    /**     * 根据 ID 获取用户     * @param {string} userId - 用户 ID     * @returns {Promise<User>} 用户对象     * @throws {Error} 当用户不存在或网络异常时抛出     * @example     * const service = new UserService('https://api.example.com');     * const user = await service.getUserById('123');     * console.log(user.name);     */    async getUserById(userId) {        const res = await fetch(`${this.apiBase}/users/${userId}`);        if (!res.ok) throw new Error(`HTTP ${res.status}`);        return res.json();    }    /**     * 创建新用户     * @param {Object} userData - 用户数据（不含 id）     * @param {string} userData.name - 姓名     * @param {string} userData.email - 邮箱     * @param {number} [userData.age] - 年龄     * @returns {Promise<string>} 新创建用户的 ID     */    async createUser(userData) {        const res = await fetch(`${this.apiBase}/users`, {            method: 'POST',            headers: { 'Content-Type': 'application/json' },            body: JSON.stringify(userData)        });        const result = await res.json();        return result.id;    }}

6.2 配置 JSDoc 生成文档

项目根目录下创建 jsdoc.config.json：

📄 jsdoc.config.json

{    "source": {        "include": ["src"],        "exclude": ["src/test", "node_modules"]    },    "opts": {        "destination": "./docs",        "recurse": true,        "readme": "./README.md",        "template": "node_modules/docdash"    },    "plugins": ["plugins/markdown"],    "templates": {        "cleverLinks": false,        "monospaceLinks": false    }}

💡 推荐模板：docdash（更现代）、 minami

6.3 生成文档命令

💻 终端命令

# 全局安装npm install -g jsdoc# 生成单个文件文档jsdoc your-file.js -d ./docs# 使用配置文件jsdoc -c jsdoc.config.json

7. 注意事项与技巧

只使用一个@returns，复杂对象用 @typedef 或内联结构。
可选属性
推荐 @property {number} [age] 的写法。
类型组合
灵活使用联合类型 {string | number}、数组 {string[]}、Promise {Promise<User>}。
继承文档
使用 @inheritdoc 或 @override 可减少重复注释。
启用 Markdown 插件，让描述更易读。
在 VS Code 等编辑器中，JSDoc 注释能提供智能提示，提升开发体验。

8. 总结

JSDoc 是 JavaScript 社区标准化的文档注释方案，通过系统的类型标注和标签使用，能够：

✅ 自动生成可读性强的 API 文档
✅ 为 IDE 提供智能提示与类型检查
✅ 提升团队协作和代码可维护性

掌握从基础标签到高级类型定义（@typedef、@template、@callback）的用法，再结合合理的项目配置与生成工具，将使你的代码文档从"备注"升级为"活文档"，贯穿开发始终。

📋 JSDoc 文档注释完整指南 · 优化补充版 · 2026