Writing API Documentation

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:

HTML: Human-readable documentation in out/doc/api/*.html
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.

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

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

Documentation Workflow

Adding New Features

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

Updating Existing Docs

Add change entry to YAML metadata
Update examples if API changed
Mark deprecations clearly
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

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');
```

Contributing

Development

​Overview

​Documentation Tooling

​Location

​Build Process

​Published Artifacts

​File Structure

​1:1 Relationship

​YAML Properties

​Documentation Template

​Basic Module Structure

​Stability Index

​Documenting Functions

​Function Signature

​Parameters

​Return Values

​Documenting Classes

​Documenting Events

​Module Events

​Class Events

​YAML Metadata

​Version History

​Deprecation

​Code Examples

​CommonJS and ES Modules

​Promises Example

​Type Annotations

​Primitive Types

​Complex Types

​Node.js Types

​Union Types

​Generic Types

​Building Documentation

​Build Commands

​Using doc-kit Directly

​Best Practices

​Be Clear and Concise

​Use Examples

​Document Edge Cases

​Link to Related APIs

​Documentation Workflow

​Adding New Features

​Updating Existing Docs

​Deprecating APIs

​Testing Documentation

​Related Resources

doc-kit Repository

doc-kit README

API Documentation

Writing Tests

​Quick Reference

Overview

Documentation Tooling

Location

Build Process

Published Artifacts

File Structure

1:1 Relationship

YAML Properties

Documentation Template

Basic Module Structure

Stability Index

Documenting Functions

Function Signature

Parameters

Return Values

Documenting Classes

Documenting Events

Module Events

Class Events

YAML Metadata

Version History

Deprecation

Code Examples

CommonJS and ES Modules

Promises Example

Type Annotations

Primitive Types

Complex Types

Node.js Types

Union Types

Generic Types

Building Documentation

Build Commands

Using doc-kit Directly

Best Practices

Be Clear and Concise

Use Examples

Document Edge Cases

Link to Related APIs

Documentation Workflow

Adding New Features

Updating Existing Docs

Deprecating APIs

Testing Documentation

Related Resources

Quick Reference