JSDoc 注释规范指南

什么是 JSDoc？

JSDoc 是一种用于为 JavaScript 和 TypeScript 代码编写结构化注释的标准文档注释格式。它可以：

• 明确函数、变量、类和接口的用途与结构；
• 通过编辑器（如 VS Code）提供更完善的自动补全和类型提示；
• 支持使用工具（如 jsdoc CLI）生成静态 HTML API 文档；
• 在未使用 TypeScript 的情况下也能提供类型提示能力。

JSDoc 注释采用 /** ... */ 的多行注释语法，通常写在函数、类、模块等声明之前。

基本语法

/**
 * 函数描述（第一行简洁描述）
 *
 * 更详细的说明（可选）
 *
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @returns {number} 两数之和
 */
function add(a, b) {
  return a + b;
}

常用标签一览

| 标签 | 含义 | 用法示例 | |------|------|----------| | @param | 描述函数参数 | @param {string} name - 用户名 | | @returns 或 @return | 描述返回值类型与意义 | @returns {boolean} - 是否验证成功 | | @type | 描述变量类型 | @type {number} | | @typedef | 自定义复合类型 | @typedef {Object} Article | | @property | 描述对象属性（配合 typedef 使用） | @property {string} title | | @example | 添加使用示例 | @example validate("admin") // true | | @deprecated | 表示方法已废弃 | @deprecated 请使用新方法 doSomethingElse() | | @async | 标记异步函数 | 与 async 函数结合使用 |

示例：函数注释

/**
 * 验证用户名是否符合规范
 * @param {string} username - 待验证的用户名
 * @returns {boolean} 是否有效
 * @example
 * isValidUsername("admin") // true
 */
function isValidUsername(username) {
  return /^[a-zA-Z0-9_]{4,16}$/.test(username);
}

示例：类型定义与对象注释

/**
 * @typedef {Object} User
 * @property {string} id - 用户唯一标识
 * @property {string} name - 用户姓名
 * @property {number} age - 用户年龄
 */

/** @type {User} */
const user = {
  id: "u001",
  name: "Alice",
  age: 28,
};

示例：异步函数注释

/**
 * 获取文章详情
 * @async
 * @param {string} articleId - 文章 ID
 * @returns {Promise<Article>} 文章详情对象
 */
async function fetchArticle(articleId) {
  const res = await fetch(`/api/articles/${articleId}`);
  return await res.json();
}

编辑器支持与工具链

• VS Code：原生支持 JSDoc，鼠标悬停时可查看注释与类型提示。
• TypeScript：虽然 TS 已自带类型，但 JSDoc 可提供更明确的函数用途与示例。
• jsdoc 工具：通过 CLI 可将注释生成 HTML 文档。
• ESLint 插件：如 eslint-plugin-jsdoc 可规范注释结构，强制标签完整性。

使用建议

• 所有公共导出函数、API 接口、复杂对象应加注释；
• 避免无意义注释，如 @param {string} str（应写明作用）；
• 示例尽量真实、清晰，可快速复制运行；
• 在 TypeScript 项目中，JSDoc 仍适用于描述业务逻辑与接口用途，而不仅限于类型。

总结

JSDoc 为 JavaScript/TypeScript 项目提供了强类型系统之外的语义增强能力。它不仅有助于代码维护、协作开发，也对构建稳定、可扩展的工程文档体系至关重要。

自动生成静态文档

npx jsdoc src --destination docs

或将其集成到构建流程中，统一输出 API 文档。