JSDoc 简介 #

什么是 JSDoc？ #

JSDoc 是一个用于 JavaScript 的 API 文档生成器。它通过解析 JavaScript 源代码中的特殊注释格式，自动生成结构化的 HTML 文档。JSDoc 是 JavaScript 社区中最流行、使用最广泛的文档生成工具之一。

核心定位 #

text

┌─────────────────────────────────────────────────────────────┐
│                         JSDoc                                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  注释解析    │  │  类型推断    │  │  HTML生成   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  模板系统    │  │  插件扩展    │  │  类型检查    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

JSDoc 的历史 #

发展历程 #

text

2008年 ─── JSDoc 1.0 诞生
    │
    │      Michael Mathews 创建
    │      基于 JavaDoc 风格
    │      基础文档生成
    │
2011年 ─── JSDoc 3.0 发布
    │
    │      完全重写
    │      插件系统
    │      模板引擎
    │
2013年 ─── 生态扩展
    │
    │      TypeScript 支持
    │      更多插件
    │      社区模板
    │
2015年 ─── ES6 支持
    │
    │      箭头函数
    │      类语法
    │      模块系统
    │
2018年 ─── 现代化改进
    │
    │      ES2015+ 完整支持
    │      更好的类型推断
    │      性能优化
    │
2020年 ─── 持续演进
    │
    │      TypeScript 集成增强
    │      VS Code 智能提示
    │      现代模板
    │
至今   ─── 行业标准
    │
    │      JavaScript 文档首选
    │      IDE 原生支持
    │      类型安全增强

里程碑版本 #

版本	时间	重要特性
1.0	2008	基础文档生成，JavaDoc 风格
2.0	2010	改进的解析器，更多标签
3.0	2011	完全重写，插件系统
3.3	2014	ES6 初步支持
3.5	2017	完整 ES6 支持，类语法
3.6	2019	TypeScript 兼容性改进
4.0	2021	现代化重构，ESM 支持

为什么选择 JSDoc？ #

文档编写的痛点 #

在没有 JSDoc 之前，JavaScript 文档面临以下问题：

javascript

// 传统方式：文档与代码分离
// README.md 或单独的文档文件

// 函数说明
// 参数: a - 第一个数字, b - 第二个数字
// 返回: 两个数字的和
function add(a, b) {
  return a + b;
}

// 问题：
// 1. 文档与代码不同步
// 2. 没有类型信息
// 3. 格式不统一
// 4. 难以维护

JSDoc 的解决方案 #

javascript

// JSDoc 方式：注释即文档

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

// 优势：
// 1. 文档与代码在一起
// 2. 有类型信息
// 3. 格式统一
// 4. 自动生成 HTML

JSDoc 的核心特点 #

1. 注释即文档 #

文档直接写在代码中，保持同步：

javascript

/**
 * 用户类
 * @class
 */
class User {
  /**
   * 创建用户实例
   * @param {string} name - 用户名
   * @param {string} email - 邮箱地址
   */
  constructor(name, email) {
    this.name = name;
    this.email = email;
  }

  /**
   * 获取用户信息
   * @returns {Object} 用户信息对象
   */
  getInfo() {
    return { name: this.name, email: this.email };
  }
}

2. 类型注解 #

支持丰富的类型定义：

javascript

/**
 * 处理用户数据
 * @param {Object} user - 用户对象
 * @param {string} user.name - 用户名
 * @param {number} user.age - 年龄
 * @param {string[]} user.tags - 标签数组
 * @returns {Promise<User>} 用户 Promise
 */
function processUser(user) {
  return Promise.resolve(new User(user.name));
}

3. 自动生成 HTML #

一键生成专业文档网站：

bash

jsdoc -c jsdoc.json

# 输出：
# out/
# ├── index.html
# ├── module-user.html
# ├── class-User.html
# └── styles/
#     └── jsdoc-default.css

4. IDE 智能提示 #

主流 IDE 原生支持：

javascript

// VS Code 中输入时会显示：
// ┌─────────────────────────────────────┐
// │ add(a: number, b: number): number   │
// │ 计算两个数字的和                      │
// │ @param a - 第一个数字                │
// │ @param b - 第二个数字                │
// │ @returns 两个数字的和                 │
// └─────────────────────────────────────┘

5. 插件系统 #

丰富的插件生态：

javascript

// jsdoc.json
{
  "plugins": [
    "plugins/markdown",           // Markdown 支持
    "node_modules/jsdoc-plugin-typescript", // TypeScript 支持
    "node_modules/better-docs"    // 更好的模板
  ]
}

6. 模板定制 #

支持自定义文档外观：

javascript

// jsdoc.json
{
  "opts": {
    "template": "node_modules/docdash"
  }
}

JSDoc 与其他文档工具对比 #

JSDoc vs TypeScript #

特性	JSDoc	TypeScript
类型检查	⚠️ 有限	✅ 完整
编译	❌ 无	✅ 有
学习成本	低	中
迁移成本	无	高
IDE 支持	✅ 好	✅ 完美
适用场景	渐进式类型	新项目

JSDoc vs TSDoc #

特性	JSDoc	TSDoc
目标语言	JavaScript	TypeScript
类型语法	JSDoc 类型	TypeScript 类型
工具支持	广泛	TypeScript 项目
学习曲线	平缓	需要了解 TS
兼容性	高	TypeScript 专用

JSDoc vs ESDoc #

特性	JSDoc	ESDoc
ES6+ 支持	✅ 好	✅ 优秀
自动推断	⚠️ 有限	✅ 强大
社区规模	大	小
维护状态	活跃	停止维护
插件生态	丰富	较少

JSDoc 的应用场景 #

1. 库和框架开发 #

为公共 API 生成文档：

javascript

/**
 * 创建 HTTP 请求客户端
 * @module HttpClient
 * @example
 * import { createClient } from 'http-client';
 * const client = createClient({ baseURL: '/api' });
 */

/**
 * 创建客户端实例
 * @param {Object} config - 配置选项
 * @param {string} config.baseURL - 基础 URL
 * @param {number} [config.timeout=5000] - 超时时间
 * @returns {HttpClient} 客户端实例
 */
export function createClient(config) {
  return new HttpClient(config);
}

2. 团队协作 #

统一团队文档规范：

javascript

/**
 * @typedef {Object} ApiResponse
 * @property {number} code - 状态码
 * @property {string} message - 响应消息
 * @property {*} data - 响应数据
 */

/**
 * 发送 API 请求
 * @template T
 * @param {string} url - 请求地址
 * @param {Object} [options] - 请求选项
 * @returns {Promise<ApiResponse & { data: T }>}
 */
async function request(url, options) {
  // ...
}

3. 代码提示增强 #

提升开发体验：

javascript

/**
 * 用户服务
 * @namespace UserService
 */
const UserService = {
  /**
   * 获取用户列表
   * @param {Object} [query] - 查询参数
   * @param {number} [query.page=1] - 页码
   * @param {number} [query.limit=10] - 每页数量
   * @returns {Promise<{ list: User[], total: number }>}
   */
  async getList(query) {
    // ...
  }
};

4. 渐进式类型迁移 #

从 JavaScript 渐进迁移到 TypeScript：

javascript

// 第一步：添加 JSDoc 注释
/**
 * @typedef {import('./types').User} User
 */

/**
 * @param {User} user
 * @returns {boolean}
 */
function validateUser(user) {
  return !!user.name && !!user.email;
}

// 第二步：迁移到 .ts 文件时，类型信息已就绪

JSDoc 的核心概念 #

注释格式 #

javascript

/**
 * 这是一个 JSDoc 注释块
 * 以 /** 开始，以 * / 结束
 * 每行以 * 开头
 * @tag {type} name - description
 */

标签（Tags） #

javascript

/**
 * @param {string} name - 参数标签
 * @returns {boolean} - 返回值标签
 * @throws {Error} - 异常标签
 * @example - 示例标签
 * @deprecated - 废弃标签
 */

类型表达式 #

javascript

/**
 * @type {string}                    // 基本类型
 * @type {string[]}                  // 数组类型
 * @type {Object<string, number>}    // 对象类型
 * @type {function(string): number}  // 函数类型
 * @type {User | Admin}              // 联合类型
 * @type {?string}                   // 可空类型
 */

JSDoc 的工作原理 #

处理流程 #

text

┌─────────────────────────────────────────────────────────────┐
│                     JSDoc 处理流程                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│  │ 源代码    │ -> │  解析器   │ -> │  AST     │              │
│  │ (.js)    │    │ (Parser) │    │          │              │
│  └──────────┘    └──────────┘    └──────────┘              │
│                                        │                     │
│                                        ▼                     │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│  │ HTML文档  │ <- │  模板     │ <- │ 文档数据  │              │
│  │ (out/)   │    │(Template)│    │ (Doclet) │              │
│  └──────────┘    └──────────┘    └──────────┘              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Doclet 结构 #

每个注释块会被解析为 Doclet 对象：

javascript

{
  kind: 'function',
  name: 'add',
  description: '计算两个数字的和',
  params: [
    { name: 'a', type: 'number', description: '第一个数字' },
    { name: 'b', type: 'number', description: '第二个数字' }
  ],
  returns: {
    type: 'number',
    description: '两个数字的和'
  },
  meta: {
    filename: 'math.js',
    lineno: 10,
    path: '/src/utils'
  }
}

JSDoc 的包结构 #

核心包 #

text

jsdoc/
├── core/           # 核心解析器
├── parser/         # 语法解析
├── doclet/         # 文档对象
├── template/       # 模板系统
├── plugin/         # 插件系统
└── cli/            # 命令行工具

常用插件 #

text

plugins/
├── markdown        # Markdown 支持
├── summare         # 摘要生成
├── sourcetag       # 源码标签
└── testdoc         # 测试文档

学习路径 #

text

入门阶段
├── 安装与配置
├── 基本注释语法
├── 常用标签
└── 生成文档

进阶阶段
├── 类型定义
├── 模块文档
├── 类和继承
└── 配置文件

高级阶段
├── 自定义模板
├── 插件开发
├── TypeScript 集成
└── 工作流集成

实战阶段
├── 库文档实战
├── 团队规范
├── CI/CD 集成
└── 最佳实践

下一步 #

现在你已经了解了 JSDoc 的基本概念，接下来学习基础语法开始实际使用 JSDoc！