docgen:Gutenberg 仓库中自动生成公开 API 文档的实战指南

原创2026-10-10 20:15:281,963 阅读
文章标签:后端前端

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 中:

  1. 读取源码并解析 AST:engine.js 调用 babel.parse() 得到 AST,再通过 getExportTokens() 过滤出顶层三类节点——ExportNamedDeclaration(命名导出)、ExportDefaultDeclaration(默认导出)、ExportAllDeclaration(整体导出,即 export * from ...)。可见 docgen 只关心 export 语句,普通声明不进入文档。
  2. 提取导出条目:对每个 export token,get-export-entries.js 将其转换为"导出条目记录",每条记录包含 localName(本地名)、exportName(导出名)、module(来源模块,若为 re-export)、lineStart/lineEnd(源码行号)。
  3. 生成中间表示(IR):get-intermediate-representation.js 为每个导出条目查找 JSDoc,组装成 { path, name, description, tags, lineStart, lineEnd } 结构。若找不到任何 JSDoc,description 会被置为常量 'Undocumented declaration.'(见 lib/index.js 第 170 行附近的 UNDOCUMENTED 定义)。
  4. 过滤与格式化输出: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 会执行三层过滤:

  1. @private 标签:通过 is-symbol-private.js 检测符号是否带 @private 标签,命中则剔除;
  2. @ignore 标签:通过 is-symbol-ignore.js 检测 @ignore 标签,命中则剔除;
  3. --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 更新文档。

登录后查看全文
gutenberg