docgen 可帮助你生成代码的公共 API。给定一个入口文件，它会以人类可读的格式输出 ES6 export 语句及其对应的 JSDoc 注释。它还通过 TypeScript Babel 插件支持 TypeScript。

一些特性：

  • 如果 export 语句不包含任何 JSDoc，它将向上查找至声明处。
  • 它可以解析相对依赖项，无论是文件还是目录。例如，import default from './dependency' 将找到 dependency.js 或 dependency/index.js
  • 对于 TypeScript 支持，所有类型必须显式标注，因为 TypeScript Babel 插件无法消费推断出的类型（毕竟它不运行 TS 编译器——它只是解析 TypeScript）。例如，如果要由 docgen 记录文档，则所有函数返回类型都必须显式标注。

安装

安装模块

npm install @wordpress/docgen --save-dev

注意：此软件包需要具有长期支持状态（检查Active LTS 或 Maintenance LTS 版本）的 Node.js 版本。它与旧版本不兼容。

用法

npm exec --no -- docgen <entry-point.js>

此命令将生成一个名为 entry-point-api.md 的文件，其中包含所有导出及其 JSDoc 注释。

CLI 选项

  • –formatter (String)：自定义格式化程序的路径，用于控制输出文件的内容。它应该是一个 CommonJS 模块，导出一个接受以下输入作为参数的函数：
    • rootDir (String)：docgen 看到的当前工作目录。
    • docPath (String)：要生成的输出文档路径。
    • symbols (Array)：找到的符号。
  • –ignore (RegExp)：用于忽略名称与其匹配的符号的正则表达式。
  • –output (String)：将包含 API 文档的输出文件。
  • –to-section (String)：将生成的文档追加到 Markdown 输出的此部分中。供默认 Markdown 格式化程序使用。依赖于 --output，如果存在自定义 --formatter，则绕过它。
  • –to-token：在 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。
  • –debug：以调试模式运行，这会输出一些对调试有用的中间文件。

Babel 配置

@wordpress/docgen 遵循默认的项目范围的 Babel 配置。像 Babel 一样，它将在项目根目录中自动搜索 babel.config.json 文件或等效文件（使用支持的扩展名）。

如果没有它，@wordpress/docgen 将以默认选项运行。换句话说，它无法解析 JSX 或其他高级语法。

示例

默认导出

入口文件 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.js：

# API

## default

[example.js#L8-L10](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.

命名导出

入口文件 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 };

npm exec --no -- docgen index.js 的输出将是 index-api.js：

# API

## addition

[example.js#L25-L25](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](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.

命名空间导出

假设入口文件为 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;
}

npm exec --no -- docgen index.js 的输出将是 index-api.js：

# API

## addition

[example-module.js#L1-L1](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](example-module.js#L1-L1)

Subtracts two numbers.

**Usage**

```js
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.

TypeScript 支持

入口文件 index.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.
}

npm exec --no -- docgen index.ts 的输出将是 index-api.js：

# API

## default

[example.js#L8-L10](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.

为此软件包做贡献

这是 Gutenberg 项目的一部分独立软件包。该项目组织为一个 monorepo。它由多个自包含的软件包组成，每个软件包都有特定的用途。此 monorepo 中的软件包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为此软件包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主贡献者指南。