@wordpress/docgen Edit

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.

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

Installation Installation

Install the module

npm install @wordpress/docgen --save-dev

Top ↑

Usage 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 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.

Top ↑

Examples Examples

Top ↑

Default export 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.

Top ↑

Named export 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.

Top ↑

Namespace export Namespace export

Let the entry point be index.js:

export * from './count';

with ./count/index.js contents being:

/**
 * Substracts two numbers.
 *
 * @example
 *
 * ```js
 * const result = substraction( 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 substraction( 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.

## substraction

[example-module.js#L1-L1](example-module.js#L1-L1)

Substracts two numbers.

**Usage**

```js
const result = substraction( 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.

Code is Poetry.