Writing API Documentation

Guide to writing and maintaining API documentation for Node.js using the doc-kit tooling.

Overview

Node.js API documentation is generated using in-house tooling from the nodejs/doc-kit repository. The tooling processes Markdown files from doc/api/ and generates both HTML and JSON outputs.

Documentation Tooling

Location

The doc-kit tooling is installed as an npm package in the tools/doc directory of the Node.js repository.

Build Process

Running make doc or make doc-only generates:

1. HTML: Human-readable documentation in out/doc/api/*.html
2. JSON: Machine-readable format in out/doc/api/*.json

Published Artifacts

Documentation is published to nodejs.org:

• HTML: nodejs.org/en/docs
• JSON: nodejs.org/api/all.json

File Structure

1:1 Relationship

There should be a 1:1 relationship between:

• Module source: lib/<module>.js
• Documentation: doc/api/<module>.md

YAML Properties

For new features, use REPLACEME for version numbers:

<!-- YAML
added: REPLACEME
-->

These will be replaced with actual version numbers during release.

Documentation Template

Basic Module Structure

# module

<!--introduced_in=v0.10.0-->

> Stability: 2 - Stable

A description and examples.

## `module.property`

<!-- YAML
added: v0.10.0
-->

- {type}

A description of the property.

## `module.someFunction(x, y, [z=100])`

<!-- YAML
added: v0.10.0
changes:
  - version: v15.0.0
    pr-url: https://github.com/nodejs/node/pull/12345
    description: A description of the change.
-->

- `x` {string} The description of the string.
- `y` {boolean} Should I stay or should I go?
- `z` {number} How many zebras to bring. **Default:** `100`.

A description of the function.

```cjs
// An example using CJS syntax.
const { someFunction } = require('module');
someFunction('a', true, 10);
```

```mjs
// An example using MJS syntax.
import { someFunction } from 'module';
someFunction('a', true, 10);
```

Stability Index

Indicate the stability of each module:

> Stability: 0 - Deprecated
> Stability: 1 - Experimental
> Stability: 2 - Stable
> Stability: 3 - Legacy

Level	Description
0	Deprecated - Avoid use, may be removed
1	Experimental - Subject to change
2	Stable - Production-ready
3	Legacy - Maintained but not actively developed

Documenting Functions

Function Signature

## `module.myFunction(required, [optional], [defaultValue=100])`

• Use backticks for the entire signature
• Square brackets [] indicate optional parameters
• Show default values with =

Parameters

- `param` {type} Description of parameter.
- `optional` {string|number} Can be multiple types. **Default:** `'default'`.
- `callback` {Function} Callback description.
  - `err` {Error|null} Error object or null.
  - `result` {Object} Result object.

Return Values

- Returns: {Promise} Resolves with result.
- Returns: {SomeClass | null} Instance or null.

Documenting Classes

## Class: `SomeClass`

A description of the class.

### `SomeClass.classMethod(anArg)`

<!-- YAML
added: v0.10.0
-->

- `anArg` {Object} Just an argument.
  - `field` {string} `anArg` can have this field.
  - `field2` {boolean} Another field. **Default:** `false`.
- Returns: {boolean} `true` if it worked.

A description of the method for humans.

### `SomeClass.nextSibling()`

<!-- YAML
added: v0.10.0
-->

- Returns: {SomeClass | null} The next `SomeClass` in line.

### `SomeClass.someProperty`

<!-- YAML
added: v0.10.0
-->

- {string}

The indication of what `someProperty` is.

Custom classes must be registered in doc-kit constants.mjs to be properly parsed in type fields.

Documenting Events

Module Events

## Event: `blerg`

<!-- YAML
added: REPLACEME
-->

- `anArg` {type} A description of the listener argument.

Modules don't usually raise events on themselves. `cluster` is the exception.

Class Events

### Event: `grelb`

<!-- YAML
added: v0.10.0
-->

- `isBlerg` {boolean}

This event is emitted on instances of `SomeClass`, not on the module itself.

YAML Metadata

Version History

<!-- YAML
added: v8.0.0
changes:
  - version: v14.0.0
    pr-url: https://github.com/nodejs/node/pull/12345
    description: Added support for async iterators.
  - version: v12.0.0
    pr-url: https://github.com/nodejs/node/pull/11111
    description: Changed default behavior.
-->

Deprecation

<!-- YAML
added: v0.10.0
deprecated: v10.0.0
-->

> Stability: 0 - Deprecated: Use `newMethod()` instead.

Code Examples

CommonJS and ES Modules

Provide examples for both module systems:

```cjs
const fs = require('node:fs');
fs.readFile('file.txt', (err, data) => {
  if (err) throw err;
  console.log(data);
});
```

```mjs
import { readFile } from 'node:fs';
readFile('file.txt', (err, data) => {
  if (err) throw err;
  console.log(data);
});
```

Promises Example

```mjs
import { readFile } from 'node:fs/promises';

try {
  const data = await readFile('file.txt', 'utf8');
  console.log(data);
} catch (err) {
  console.error(err);
}
```

Type Annotations

Primitive Types

- {string}
- {number}
- {boolean}
- {symbol}
- {bigint}
- {null}
- {undefined}

Complex Types

- {Object}
- {Array}
- {Function}
- {Promise}
- {AsyncIterator}

Node.js Types

- {Buffer}
- {URL}
- {Stream}
- {http.Server}
- {EventEmitter}

Union Types

- {string | Buffer}
- {number | null}
- {Function | AsyncFunction}

Generic Types

- {Array<string>}
- {Promise<Object>}
- {Map<string, number>}

Building Documentation

Build Commands

# Build Node.js and documentation
make doc

# Build only documentation (with existing Node.js)
NODE=/path/to/node make doc-only

# Serve documentation locally
make docserve

# Open in browser
make docopen

# Clean documentation artifacts
make docclean

Using doc-kit Directly

# From tools/doc directory
npx doc-kit

# Or from repository root
tools/doc/node_modules/.bin/doc-kit generate ...

Best Practices

Be Clear and Concise

<!-- Good -->
Reads the entire contents of a file asynchronously.

<!-- Bad -->
This function allows you to read files from the filesystem.

Use Examples

Provide practical examples that users can copy and use:

```javascript
const fs = require('node:fs');

// Good: Complete, runnable example
fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) throw err;
  console.log(data);
});
```

Document Edge Cases

If `path` is a directory, the callback receives an `EISDIR` error.

On Windows, symbolic links are not followed.

Link to Related APIs

See also: [`fs.readFileSync()`][], [`fs.promises.readFile()`][].

[`fs.readFileSync()`]: #fsreadfilesyncpath-options
[`fs.promises.readFile()`]: #fspromisesreadfilepath-options

Documentation Workflow

Adding New Features

1. Add documentation alongside code changes
2. Use REPLACEME for version numbers
3. Add YAML metadata with added: REPLACEME
4. Provide examples for both CJS and ESM
5. Build and verify documentation renders correctly

Updating Existing Docs

1. Add change entry to YAML metadata
2. Update examples if API changed
3. Mark deprecations clearly
4. Update related documentation if necessary

Deprecating APIs

<!-- YAML
added: v0.10.0
deprecated: v14.0.0
-->

> Stability: 0 - Deprecated: Use [`newApi()`][] instead.

This method is deprecated and will be removed in a future version.
Use [`newApi()`][] for new code.

[`newApi()`]: #newapi

Testing Documentation

Documentation examples are tested as part of the test suite:

# Run documentation tests
make test-doc

# Run full test suite (includes doc tests)
make -j4 test

Related Resources

doc-kit Repository

Documentation tooling source

doc-kit README

Tool usage documentation

API Documentation

Published Node.js API docs

Writing Tests

Test your documentation

Quick Reference

# Module Name

<!--introduced_in=vX.X.X-->

> Stability: 2 - Stable

## `module.method(required, [optional=default])`

<!-- YAML
added: REPLACEME
-->

- `required` {type} Description.
- `optional` {type} Description. **Default:** `default`.
- Returns: {type} Description.

Method description.

```cjs
const { method } = require('module');
method('value');
```

```mjs
import { method } from 'module';
method('value');
```