docgen:Gutenberg 仓库中自动生成公开 API 文档的实战指南
docgen:Gutenberg 仓库中自动生成公开 API 文档的实战指南
@wordpress/docgen 是 Gutenberg 仓库(WordPress 的 Block Editor 项目)中负责从 ES6 模块入口自动生成公开 API 文档的工具包。它解析入口文件中的 export 语句与其对应的 JSDoc 注释,输出人类可读的 Markdown 文档,并原生支持 TypeScript。读完本文,你将掌握 docgen 的安装、CLI 用法、四种导出场景(默认导出、命名导出、命名空间导出、TypeScript)、JSDoc 解析规则、符号过滤机制,以及如何将生成的文档嵌入既有 README,并理解其从 AST 到最终文档的完整流水线。
docgen 是什么
docgen 是一个小型的文档生成引擎:给定一个入口点文件,它会输出该文件的 ES6 导出语句及其对应的 JSDoc 注释,格式为人类可读的 Markdown。它的设计目标非常聚焦——只关心"公开 API",即模块对外导出的部分。
从 package.json 的定义看,它的官方描述是 "Autogenerate public API documentation from exports and JSDoc comments",关键词为 wordpress、gutenberg、jsdoc、documentation。当前仓库内版本为 2.57.0,Node.js 运行环境要求 >=22.13.0(见 engines 字段)。
docgen 有以下几个核心特性:
- JSDoc 智能回溯:如果 export 语句本身不带 JSDoc,它会向上回溯到对应的声明处查找 JSDoc。例如
export { addition }没有注释时,docgen 会去文件里找到function addition() {}的声明并读取其上方注释。 - 相对依赖解析:能够解析相对依赖,无论是文件还是目录。例如
import default from './dependency'会找到dependency.js或dependency/index.js。 - TypeScript 支持:通过 TypeScript Babel 插件解析
.ts/.tsx文件,但所有类型必须显式标注——docgen 只做语法解析,不运行 TypeScript 编译器,因此无法消费推断类型。例如所有函数返回类型必须显式标注,否则无法被 docgen 记录。
安装与运行环境
在任意项目的开发依赖中安装:
npm install @wordpress/docgen --save-dev
注意:该包要求 Node.js 版本处于长期支持(LTS)状态(Active LTS 或 Maintenance LTS),不兼容更老的版本。当前仓库的 package.json 明确声明 "node": ">=22.13.0"。
安装后,docgen 可执行命令会被注册到 node_modules/.bin(见 package.json 的 bin 字段,实际入口为 bin/cli.js)。
基本用法
npm exec --no -- docgen <entry-point.js>
该命令会在入口文件同目录下生成一个名为 entry-point-api.md 的文件,包含所有导出及其 JSDoc 注释。例如对 index.js 执行 npm exec --no -- docgen index.js,默认输出文件为 index-api.md(从 lib/index.js 的实现可以看到,默认输出路径由 inputBase + '-api.md' 拼接而成;README 示例中写作 index-api.js 属于笔误,实际为 Markdown 文件)。
如果想自定义输出文件,使用 --output:
npm exec --no -- docgen index.js --output docs/api.md
CLI 选项详解
docgen 的命令行参数由 bin/cli.js 通过 optionator 解析,完整选项如下:
| 选项 | 类型 | 说明 |
|---|---|---|
--formatter |
String | 自定义格式化器路径。它是一个 CommonJS 模块,导出一个函数,接收三个参数:rootDir(docgen 视角下的当前工作目录,String)、docPath(待生成的输出文档路径,String)、symbols(解析出的符号数组,Array)。传入后默认 Markdown 格式化器将被绕过。 |
--ignore |
RegExp | 一个正则表达式,用于忽略名称匹配该正则的符号。 |
--output |
String | 存放 API 文档的输出文件。 |
--to-section |
String | 将生成的文档追加到 Markdown 输出中的指定章节(按标题名定位)。仅供默认 Markdown 格式化器使用;依赖 --output,且会绕过传入的自定义 --formatter。 |
--to-token |
Boolean | 将生成的文档嵌入 Markdown 输出的起始/结束标记之间。仅供默认 Markdown 格式化器使用;依赖 --output,同样绕过自定义 --formatter。默认标记为 <!-- START TOKEN(Autogenerated API docs) --> 与 <!-- END TOKEN(Autogenerated API docs) -->。 |
--use-token |
String | 自定义标记中的字符串。例如 --use-token my-api 会查找 <!-- START TOKEN(my-api) --> 与 <!-- END TOKEN(my-api) -->。依赖 --to-token,默认值为 Autogenerated API docs(见 cli.js 的默认值)。 |
--debug |
Boolean | 调试模式,输出一些便于排查问题的中间文件。默认 false。 |
几个选项之间的依赖关系值得注意(cli.js 源码中通过 dependsOn 声明):
--to-section依赖--output;--to-token依赖--output;--use-token依赖--to-token。
调试模式与中间文件
在 lib/index.js 中,开启 --debug 后会在入口文件同目录写出三个 JSON 中间产物,便于理解解析过程:
入口名-ast.json:Babel 解析出的完整 AST;入口名-exports.json:从 AST 中提取出的 export 节点(tokens);入口名-ir.json:中间表示(Intermediate Representation),即最终用于生成文档的符号结构。
从入口文件到 API 文档:内部流水线
docgen 的处理流程可以拆成清晰的四步,全部集中在 lib/index.js 与 lib/engine.js 中:
- 读取源码并解析 AST:
engine.js调用babel.parse()得到 AST,再通过getExportTokens()过滤出顶层三类节点——ExportNamedDeclaration(命名导出)、ExportDefaultDeclaration(默认导出)、ExportAllDeclaration(整体导出,即export * from ...)。可见 docgen 只关心 export 语句,普通声明不进入文档。 - 提取导出条目:对每个 export token,get-export-entries.js 将其转换为"导出条目记录",每条记录包含
localName(本地名)、exportName(导出名)、module(来源模块,若为 re-export)、lineStart/lineEnd(源码行号)。 - 生成中间表示(IR):get-intermediate-representation.js 为每个导出条目查找 JSDoc,组装成
{ path, name, description, tags, lineStart, lineEnd }结构。若找不到任何 JSDoc,description会被置为常量'Undocumented declaration.'(见 lib/index.js 第 170 行附近的 UNDOCUMENTED 定义)。 - 过滤与格式化输出:
lib/index.js先过滤掉私有符号与忽略符号(详见下文"符号过滤"),再交给默认 Markdown 格式化器或自定义 formatter 写出文件。
其中第三步的 JSDoc 回溯 是 docgen 最有价值的能力。get-intermediate-representation.js 的 getJSDoc() 逻辑为:
- 优先取 export token 自带的 JSDoc;
- 若没有,则在当前文件的 AST 中查找同名声明(
ClassDeclaration、FunctionDeclaration、TSDeclareFunction、VariableDeclaration等),读取该声明的 JSDoc; - 若该名字来自 import 语句,则递归解析依赖文件(
parseDependency),从依赖的 IR 中按名字查找文档。
相对依赖解析规则
lib/index.js 定义了一组完整的扩展名与查找顺序。当遇到相对路径(以 . 开头)时:
- 支持的扩展名列表:
.js、.jsx、.mjs、.cjs、.ts、.tsx、.mts、.cts; - 若目标路径本身带扩展名则直接使用;
- 否则依次尝试
目标路径 + 扩展名与目标路径/index + 扩展名; - 若全部失败,会在 stderr 打印
Relative path does not exists.及基路径、相对路径信息后以状态码 1 退出。
这就是 README 中 "import default from './dependency' 会找到 dependency.js 或 dependency/index.js" 的底层实现。
JSDoc 解析细节
JSDoc 的解析由 get-jsdoc-from-token.js 完成,它使用 comment-parser 库(spacing: 'preserve')解析函数/类声明前的块注释。几个值得注意的行为:
- 参数计数与限定参数:
@param标签会按顺序计数;带点号的限定参数(如@param {Object} props下的@param {string} props.name)会共享其父参数的索引位置,用于从 TS 类型中提取成员类型。 - 可选参数:格式化时可选参数的类型会输出为
<a href="https://link.gitcode.com/i/214acb2a23a95401b7c69cb40810b79b" target="_blank">type]形式(见 [formatter.js 的 getTypeOutput)。 - 无标签时的类型推断:若 JSDoc 没有任何标签,docgen 会尝试从 TS 类型注解中推断并补一个
type标签。
关于类型信息的来源,get-type-annotation.js 实现了完整的 TypeScript 类型注解字符串化:支持联合类型 |、交叉类型 &、数组 T[]、元组、函数类型 ( params ) => return、索引访问 T['k']、映射类型、字面量类型、泛型引用 Type< A, B > 等数十种 Babel TS 节点。
还有一个非常"Gutenberg 特色"的细节:get-type-annotation.js 中的 unwrapWrappedSelectors() 会解包 createSelector 与 createRegistrySelector 这类 selector 包装函数,从参数中提取内部箭头函数的类型。这是因为 Gutenberg 大量使用 @wordpress/data 的 selector 包装模式,直接解析无法拿到被包裹函数的参数类型,所以做了特判处理。
四种导出场景的完整示例
默认导出(Default export)
入口文件 index.js:
/**
* Adds two numbers.
*
* @param {number} term1 First number.
* @param {number} term2 Second number.
* @return {number} The result of adding the two numbers.
*/
export default function addition( term1, term2 ) {
// Implementation would go here.
}
执行 npm exec --no -- docgen index.js 后生成的 index-api.md:
# API
## default
example.js#L8-L10
Adds two numbers.
**Parameters**
- **term1** `number`: First number.
- **term2** `number`: Second number.
**Returns**
`number` The result of adding the two numbers.
注意:默认导出的符号名在文档中显示为 default。在 get-export-entries.js 中,ExportDefaultDeclaration 会尝试获取声明名(Identifier 取名字、AssignmentExpression 取左侧名、其余取 id?.name ?? '*default*'),但 exportName 固定为 'default'。
命名导出(Named export)
入口文件 index.js:
/**
* Adds two numbers.
*
* @param {number} term1 First number.
* @param {number} term2 Second number.
* @return {number} The result of adding the two numbers.
*/
function addition( term1, term2 ) {
return term1 + term2;
}
/**
* Adds two numbers.
*
* @deprecated Use `addition` instead.
*
* @param {number} term1 First number.
* @param {number} term2 Second number.
* @return {number} The result of adding the two numbers.
*/
function count( term1, term2 ) {
return term1 + term2;
}
export { count, addition };
生成的 index-api.md:
# API
## addition
example.js#L25-L25
Adds two numbers.
**Parameters**
- **term1** `number`: First number.
- **term2** `number`: Second number.
**Returns**
`number` The result of adding the two numbers.
## count
example.js#L25-L25
> **Deprecated** Use `addition` instead.
Adds two numbers.
**Parameters**
- **term1** `number`: First number.
- **term2** `number`: Second number.
**Returns**
`number` The result of adding the two numbers.
这个示例展示了三个要点:
- export 语句本身没有 JSDoc,docgen 回溯到函数声明处读取注释;
@deprecated标签会被渲染为> **Deprecated** ...的引用块(见 formatter.js 的 formatDeprecated);- 符号按名称字母序排序输出(formatter.js 中的 sort),因此
addition排在count前面。
命名空间导出(Namespace export / export *)
入口文件 index.js:
export * from './count';
其中 ./count/index.js 的内容为:
/**
* Subtracts two numbers.
*
* @example
*
* ```js
* const result = subtraction( 5, 2 );
* console.log( result ); // Will log 3
* ```
*
* @param {number} term1 First number.
* @param {number} term2 Second number.
* @return {number} The result of subtracting the two numbers.
*/
export function subtraction( term1, term2 ) {
return term1 - term2;
}
/**
* Adds two numbers.
*
* @example
*
* ```js
* const result = addition( 5, 2 );
* console.log( result ); // Will log 7
* ```
*
* @param {number} term1 First number.
* @param {number} term2 Second number.
* @return {number} The result of adding the two numbers.
*/
export function addition( term1, term2 ) {
// Implementation would go here.
return term1 - term2;
}
生成的 index-api.md:
# API
## addition
example-module.js#L1-L1
Adds two numbers.
**Usage**
```js
const result = addition( 5, 2 );
console.log( result ); // Will log 7
Parameters
- term1
number: First number. - term2
number: Second number.
Returns
number The result of adding the two numbers.
subtraction
example-module.js#L1-L1
Subtracts two numbers.
Usage
const result = subtraction( 5, 2 );
console.log( result ); // Will log 3
Parameters
- term1
number: First number. - term2
number: Second number.
Returns
number The result of subtracting the two numbers.
`export * from './count'` 会触发依赖解析:在 <a href="https://link.gitcode.com/i/af22ad2a0d9e0bcdcdc969828eab6c39" target="_blank">get-intermediate-representation.js</a> 中,`localName === '*'` 时会把依赖模块中所有非 `default` 的符号展开进当前文档。此外,`@example` 标签被渲染为 `**Usage**` 小节,其中内嵌的 Markdown 代码块原样保留。
### TypeScript 支持
入口文件 `index.ts`:
```ts
/**
* Adds two numbers.
*
* @param term1 First number.
* @param term2 Second number.
* @return The result of adding the two numbers.
*/
export default function addition( term1: number, term2: number ): number {
// Implementation would go here.
}
生成的 index-api.md:
# API
## default
example.js#L8-L10
Adds two numbers.
**Parameters**
- **term1** `number`: First number.
- **term2** `number`: Second number.
**Returns**
`number` The result of adding the two numbers.
注意 JSDoc 中并未写类型(@param term1 无 {number}),但输出文档中参数与返回类型都完整呈现——这正是 get-type-annotation.js 的职责:当 tag.type 缺失时,从 TS 的 typeAnnotation 中提取。前提是函数签名必须显式标注类型,因为 docgen 不运行 TypeScript 编译器,无法从推断类型中获取信息。
Babel 配置:解析 JSX 等高级语法的前提
@wordpress/docgen 遵循 Babel 的项目级配置(project-wide configuration):与 Babel 一致,它会在项目根目录自动查找 babel.config.json 文件(或其支持扩展名的等价文件,如 babel.config.js、.cjs、.mjs)。
如果没有该配置,docgen 将以默认选项运行,无法解析 JSX 或其他高级语法。这意味着:如果你要对包含 JSX 的入口文件(如 src/index.jsx)运行 docgen,必须在项目根目录提供一份 Babel 配置(例如仓库根目录的 babel.config.js),其中应包含所需的 preset(如 @babel/preset-react 与 @babel/preset-typescript)。
在 Gutenberg 仓库中,docgen 正是依托根目录的 Babel 配置来解析各 package 的 src/index.js / .ts / .tsx 入口的。
符号过滤:@private、@ignore 与 --ignore
生成文档前,lib/index.js 会执行三层过滤:
@private标签:通过 is-symbol-private.js 检测符号是否带@private标签,命中则剔除;@ignore标签:通过 is-symbol-ignore.js 检测@ignore标签,命中则剔除;--ignore正则:若 CLI 传入了--ignore <RegExp>,则symbol.name.match( regex )命中的符号被剔除。
三者都基于 get-symbol-tags-by-name.js 从符号的 tags 数组中按标签名查找。
在 Gutenberg 的实际用法中,tools/docs/update-api-docs.js 调用 docgen 时传入了 --ignore '/unstable|experimental/i',即把名称中包含 unstable 或 experimental 的 API 从公开文档中排除——这些是 Gutenberg 中尚未稳定、随时可能变更的 API,不适合写入面向开发者的正式文档。
将文档嵌入既有 README:--to-section 与 --to-token
docgen 的默认行为是生成一个全新的 Markdown 文件,但实际项目中更常见的需求是把 API 文档自动嵌入到已有的 README 中,这正是 --to-token(配合 --use-token)与 --to-section 的用途。
标记嵌入(--to-token)
在目标 README 中放置一对 HTML 注释标记:
<!-- START TOKEN(Autogenerated API docs) -->
<!-- END TOKEN(Autogenerated API docs) -->
然后执行:
npm exec --no -- docgen src/index.js --output README.md --to-token
docgen 会把生成的文档插入两个标记之间,且会根据标记所在位置的标题层级自动调整文档内标题的深度(embed.js 的 getHeadingIndex 会向上查找最近的标题,将新内容的标题设为 最近标题深度 + 1)。若标记缺失,会抛出 Start and/or end tokens for ... not found. 错误(见 markdown/index.js)。
通过 --use-token my-api 可以自定义标记名:
npm exec --no -- docgen src/index.js --output README.md --to-token --use-token my-api
对应查找 <!-- START TOKEN(my-api) --> 与 <!-- END TOKEN(my-api) -->。
章节嵌入(--to-section)
若 README 中已有固定的 ## API 等章节标题,也可以按标题定位插入:
npm exec --no -- docgen src/index.js --output README.md --to-section "API"
实现上,markdown/index.js 使用 mdast-util-inject 将新内容注入到指定标题之下;若标题不存在,则报 Heading API not found.。
Gutenberg 仓库中的真实应用
update-api-docs.js 是 Gutenberg 文档自动化的核心脚本,它扫描所有 packages 的 README 与 docs/reference-guides/data/ 下的数据文档,找出含 START TOKEN 标记的文件,逐个执行 docgen 并原地更新。其关键实现:
- 通过模块解析定位
@wordpress/docgen的 bin 路径,而非依赖node_modules/.bin(第 25-31 行); - 标记模式支持
<!-- START TOKEN(Autogenerated actions|src/actions.js) -->这种带来源路径的写法——|后指定该 token 对应的源码入口(第 72 行); - 未指定路径时默认查找包内的
src/index.{js,jsx,mjs,cjs,ts,tsx,mts,cts}(findDefaultSourcePath); - 每个文件可能有多个 token,脚本串行、一次更新一个 token,避免并发进程互相覆盖(第 223-226 行)。
实际生成的文档示例见 docs/reference-guides/data/data-core-editor.md,其中 <!-- START TOKEN(Autogenerated selectors|../../../packages/editor/src/store/selectors.js) --> 标记下方的 Selectors 章节,就是 docgen 从 packages/editor/src/store/selectors.js 自动生成的——每个 selector 都带 _Parameters_ / _Returns_ 说明。
自定义 formatter:完全掌控输出格式
默认的 Markdown 格式化器未必满足所有需求。通过 --formatter 可以传入自定义格式化模块,其签名为:
// my-formatter.js
module.exports = function formatter( rootDir, docPath, symbols, headingTitle ) {
// rootDir: docgen 视角的当前工作目录
// docPath: 输出文档路径
// symbols: 过滤后的符号数组
// headingTitle: 标题文字(默认 'API')
// 返回要写入文件的字符串
return '';
};
执行:
npm exec --no -- docgen index.js --output api.md --formatter ./my-formatter.js
从 lib/index.js 的 runCustomFormatter 看,docgen 会用 require() 加载该模块并把 ( rootDir, doc, symbols, headingTitle ) 传入,将返回值写入 --output 指定的文件。注意传入自定义 formatter 后,--to-section / --to-token 会被绕过(README 与 cli.js 均有说明)。
测试与验证
docgen 自带 vitest 测试(packages/docgen/test/),覆盖引擎、Markdown 格式化器、导出条目提取、中间表示、JSDoc 提取与类型注解等关键模块:
- test/engine.js:验证
engine( undefined )返回空的 IR; - test/formatter-markdown.js:验证格式化器对多行描述、代码块、列表、
*Parameters*/*Returns*等结构的渲染,包括"连字符换行合并"(Client-side hyphen-\nation会被合并为Client-side hyphenation.)这一细节——对应 formatter.js 中的正则处理。
小结
@wordpress/docgen 是一个小而精的 API 文档生成器:入口即 export,JSDoc 即内容,依赖解析与 TS 类型提取补齐细节,三层过滤控制公开边界,token 嵌入机制让文档可以持续自动更新。在 Gutenberg 仓库中,它支撑着 docs/reference-guides/data/ 下全部数据 store 的 API 文档与各 package README 的自动化维护——理解了它的流水线(AST → export tokens → IR → 过滤 → 格式化),你就能在自己的项目中复刻这套"代码即文档、文档随代码更新"的实践。
如需深入,可以继续阅读 packages/docgen/CHANGELOG.md 了解版本演进,或查看 tools/docs/update-api-docs.js 学习如何在 monorepo 中批量驱动 docgen 更新文档。