红宝书第五十五讲：文档生成（JSDoc vs ESDoc）：像写笔记一样自动生成说明书

---

红宝书第五十五讲：文档生成（JSDoc vs ESDoc）：像写笔记一样自动生成说明书

文档生成工具 = 代码注释 → 精美网页文档，解决维护文档的烦恼。基于参考资料中的工具介绍¹²：

资料取自《JavaScript高级程序设计（第5版）》。
查看总目录：红宝书学习大纲

---

一、JSDoc：最常用的“说明书生成器”

适用场景：普通JavaScript项目，兼容性强。

1. 如何写注释（资料2中的基础用法²）：

   /**
    * 计算用户年龄（示例函数）
    * @param {number} birthYear 出生年份
    * @returns {number} 年龄
    */
   function calculateAge(birthYear) {
     return new Date().getFullYear() - birthYear;
   }

   标签解释：

2. @param：参数说明
3. @returns：返回值说明

4. 生成文档步骤（基于资料2的JsDoc Toolkit、documentation.js²）：

   flowchart LR
    写带注释的代码 --> 运行JSDoc工具 --> 生成HTML/Markdown文档

命令示例：

# 使用documentation.js生成HTML
npm install documentation
documentation build src/** -f html -o docs

---

二、ESDoc：专为ES6模块设计的“高配版”

特点（资料1中的功能描述¹）：

• 强制要求：代码必须用ES6模块 (import/export)
• 进阶功能：自动链接源代码、插件扩展

注释示例：

/** 
 * 用户类，管理用户信息 
 */
export class User {
  /**
   * @param {string} name 用户名
   */
  constructor(name) {
    this.name = name;
  }
}

生成命令（资料1提及的ESDoc用法¹）：

npm install esdoc
esdoc -c esdoc.json  # 配置文件指定入口文件

---

三、工具对比：JSDoc vs ESDoc

| 工具 | 优点 | 缺点 | 适用场景 |
|--------------|----------------------------|-------------------------|-------------------|
| JSDoc | 兼容性好，灵活 | 需要手动配置较多² | 传统JS项目 |
| ESDoc | 自动化高，支持插件 | 强制ES6模块¹ | 大型现代项目（如React） |

---

目录：总目录

上篇文章：红宝书第五十四讲：设计原则SOLID与DRY：写出优雅代码的秘密

脚注

---

1. 《JavaScript高级程序设计（第5版）》描述ESDoc的高级功能和ES6模块要求 ↩
2. 《JavaScript高级程序设计（第5版）》介绍JsDoc Toolkit和documentation.js的基础使用 ↩