红宝书第五十五讲：文档生成（JSDoc vs ESDoc）：像写笔记一样自动生成说明书
红宝书第五十五讲：文档生成（JSDoc vs ESDoc）：像写笔记一样自动生成说明书
文档生成工具 = 代码注释 → 精美网页文档，解决维护文档的烦恼。基于参考资料中的工具介绍12：
资料取自《JavaScript高级程序设计（第5版）》。
查看总目录：红宝书学习大纲
一、JSDoc：最常用的“说明书生成器”
适用场景：普通JavaScript项目，兼容性强。
- 如何写注释（资料2中的基础用法2）：
/*** 计算用户年龄（示例函数）* @param {number} birthYear 出生年份* @returns {number} 年龄*/
function calculateAge(birthYear) {return new Date().getFullYear() - birthYear;
}
标签解释：
@param：参数说明@returns：返回值说明
- 生成文档步骤（基于资料2的JsDoc Toolkit、documentation.js2）：
命令示例：
# 使用documentation.js生成HTML
npm install documentation
documentation build src/** -f html -o docs
二、ESDoc：专为ES6模块设计的“高配版”
特点（资料1中的功能描述1）：
- 强制要求：代码必须用ES6模块 (
import/export) - 进阶功能：自动链接源代码、插件扩展
注释示例：
/** * 用户类，管理用户信息 */
export class User {/*** @param {string} name 用户名*/constructor(name) {this.name = name;}
}
生成命令（资料1提及的ESDoc用法1）：
npm install esdoc
esdoc -c esdoc.json # 配置文件指定入口文件
三、工具对比：JSDoc vs ESDoc
| 工具 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| JSDoc | 兼容性好，灵活 | 需要手动配置较多2 | 传统JS项目 |
| ESDoc | 自动化高，支持插件 | 强制ES6模块1 | 大型现代项目（如React） |
目录：总目录
上篇文章：红宝书第五十四讲：设计原则SOLID与DRY：写出优雅代码的秘密
脚注
《JavaScript高级程序设计（第5版）》描述ESDoc的高级功能和ES6模块要求 ↩︎ ↩︎ ↩︎ ↩︎
《JavaScript高级程序设计（第5版）》介绍JsDoc Toolkit和documentation.js的基础使用 ↩︎ ↩︎ ↩︎ ↩︎