JSDoc注释规范与使用详解

JSDoc 是 JavaScript 开发中不可或缺的结构化注释标准，通过 `@param`、`@returns`、`@example` 等语义化标签，不仅能大幅提升代码可读性与可维护性，还能自动生成专业 API 文档、无缝集成 ESLint 和 CI 流程以保障注释质量；无论你是为函数精准标注类型与行为、为异步方法明确 Promise 返回、为类定义清晰表达继承关系，还是推动团队统一协作规范，掌握这套简洁实用的注释实践，都能让你的代码更健壮、更易懂、更经得起时间考验。

JSDoc 是一种用于为 JavaScript 代码添加结构化注释的文档标准，它不仅能提升代码可读性，还能配合工具自动生成 API 文档。遵循统一的 JSDoc 注释规范，有助于团队协作和后期维护。以下是实用的 JSDoc 注释编写指南。

基础语法与常用标签

JSDoc 注释以 /** 开头，每行以 * 对齐，使用特定标签描述代码元素。常见标签包括：

例如：

/**
 * 计算两个数的和
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 两数之和
 * @example
 *   add(2, 3); // 返回 5
 */
function add(a, b) {
  return a + b;
}

函数与方法注释规范

每个公开函数或类方法都应包含 JSDoc 注释，明确其行为边界。

注意点：

• 必须注明所有参数类型和含义，即使类型简单
• 返回值类型不可省略，void 类型也需标注 {@link void}
• 若函数有副作用（如修改全局变量），应在描述中说明
• 异步函数返回值应标注为 {Promise}

示例：

/**
 * 获取用户信息
 * @async
 * @param {string} userId - 用户唯一标识
 * @returns {Promise<Object>} 用户对象
 * @throws {Error} 网络请求失败时抛出
 */
async function fetchUser(userId) {
  const res = await fetch(`/api/users/${userId}`);
  if (!res.ok) throw new Error('Failed to fetch');
  return res.json();
}

类与属性文档化

类定义应使用 @class 或 @constructor 标注，属性建议使用 @property。

• 私有成员可用 @private 标识
• 静态成员使用 @static
• 继承关系可通过 @extends 表达

示例：

/**
 * 用户模型类
 * @class
 * @extends {BaseModel}
 */
class User extends BaseModel {
  /**
   * 用户名称
   * @type {string}
   * @property
   */
  name;
<p>/**</p>

• 创建新用户实例
• @param {string} name - 用户名 */ constructor(name) { super(); this.name = name; } }

生成与维护文档

可使用工具如 jsdoc、TypeDoc 或 VS Code 插件解析注释并输出 HTML 文档。

建议做法：

• 将文档生成纳入构建流程，定期更新
• 在 CI 中校验 JSDoc 完整性（如参数缺失）
• 结合 ESLint 使用 eslint-plugin-jsdoc 提高注释质量
• 保持注释与代码同步，避免过时描述

基本上就这些，坚持写清晰的 JSDoc，长期来看能显著降低维护成本。

好了，本文到此结束，带大家了解了《JSDoc注释规范与使用详解》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！