云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/docgen

查看官方原文 ↗
💡 云策文档标注

概述

@wordpress/docgen 是一个用于生成代码公共 API 文档的工具，支持 ES6 导出语句和 JSDoc 注释的提取，并可通过 TypeScript Babel 插件提供 TypeScript 支持。它通过解析入口文件，输出人类可读的格式，如 Markdown 文件。

关键要点

  • 自动查找 JSDoc：如果导出语句没有 JSDoc，会向上查找直到声明处。
  • 依赖解析：支持解析相对依赖，如文件或目录（例如 ./dependency 会匹配 dependency.js 或 dependency/index.js）。
  • TypeScript 支持：需显式注解类型，因为 TypeScript Babel 插件无法处理推断类型。
  • 安装要求：通过 npm install @wordpress/docgen --save-dev 安装，需要 Node.js 长期支持版本。
  • 基本用法：使用 npx docgen 生成 API 文档文件。
  • CLI 选项：包括自定义格式化器、忽略符号、输出文件、追加到 Markdown 部分或令牌等。
  • Babel 配置：遵循项目范围的 Babel 配置，如 babel.config.json，否则使用默认选项。

代码示例

// 默认导出示例
/**
 * 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.
}

注意事项

  • TypeScript 支持需显式注解所有类型，包括函数返回类型。
  • CLI 选项如 --to-section 和 --to-token 依赖于 --output，并会绕过自定义 --formatter。
  • 项目需有 Babel 配置文件以支持 JSX 等高级语法，否则使用默认解析。
📄 原文内容

docgen helps you to generate the public API of your code. Given an entry point file, it outputs the ES6 export statements and their corresponding JSDoc comments in human-readable format. It also supports TypeScript via the TypeScript babel plugin.

Some characteristics:

  • If the export statement doesn’t contain any JSDoc, it’ll look up for JSDoc up to the declaration.
  • It can resolve relative dependencies, either files or directories. For example, import default from './dependency' will find dependency.js or dependency/index.js
  • For TypeScript support, all types must be explicitly annotated as the TypeScript Babel plugin is unable to consume inferred types (it does not run the TS compiler, after all—it merely parses TypeScript). For example, all function return types must be explicitly annotated if they are to be documented by docgen.

Installation

Install the module

npm install @wordpress/docgen --save-dev

Note: This package requires Node.js version with long-term support status (check Active LTS or Maintenance LTS releases). It is not compatible with older versions.

Usage

npx docgen <entry-point.js>

This command will generate a file named entry-point-api.md containing all the exports and their JSDoc comments.

CLI options

  • –formatter (String): A path to a custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
    • rootDir (String): current working directory as seen by docgen.
    • docPath (String): path of the output document to generate.
    • symbols (Array): the symbols found.
  • –ignore (RegExp): A regular expression used to ignore symbols whose name match it.
  • –output (String): Output file that will contain the API documentation.
  • –to-section (String): Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on --output and bypasses the custom --formatter passed, if any.
  • –to-token: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on --output and bypasses the custom --formatter passed, if any.
    • Start token: <!-- START TOKEN(Autogenerated API docs) -->
    • End token: <!-- END TOKEN(Autogenerated API docs) -->
  • –use-token (String): This options allows you to customize the string between the tokens. For example, --use-token my-api will look up for the start token <!-- START TOKEN(my-api) --> and the end token <!-- END TOKEN(my-api) -->. Depends on --to-token.
  • –debug: Run in debug mode, which outputs some intermediate files useful for debugging.

Babel Configuration

@wordpress/docgen follows the default project-wide configuration of Babel. Like Babel, it will automatically search for a babel.config.json file, or an equivalent one using the supported extensions, in the project root directory.

Without it, @wordpress/docgen runs with the default option. In other words, it cannot parse JSX or other advanced syntaxes.

Examples

Default export

Entry point 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.
}

Output of npx docgen index.js would be 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.

Named export

Entry point 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 };

Output of npx docgen index.js would be 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.

Namespace export

Let the entry point be index.js:

export * from './count';

with ./count/index.js contents being:

/**
 * 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;
}

Output of npx docgen index.js would be 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 support

Entry point 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.
}

Output of npx docgen index.ts would be 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.

Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.