Generating API Documentation for JavaScript and TypeScript Projects
documentation, esdoc, jsdoc, and typedoc are tools that turn code comments into readable websites or static files. They help teams understand how to use libraries without reading source code. jsdoc is the oldest and works with plain JavaScript. typedoc is built specifically for TypeScript and reads type definitions directly. documentation focuses on modern JavaScript and Flow types with a clean output. esdoc was popular for ES6 but is now largely inactive. Choosing the right one depends on your language (JS vs TS) and how much automation you want.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Documentation Generators: documentation vs esdoc vs jsdoc vs typedoc
Building maintainable libraries requires clear documentation. The tools documentation, esdoc, jsdoc, and typedoc all parse source code to create reference sites, but they handle languages and configuration very differently. Let's compare how they work in real engineering scenarios.
🗣️ Language Support: JavaScript vs TypeScript
documentation works best with JavaScript and Flow types.
- It parses JSDoc comments and can infer some types from Flow.
- Does not natively understand TypeScript syntax without transpilation.
# documentation: Build from JS files
npx documentation build src/**/*.js -f html -o docs
esdoc was designed for ES6 JavaScript.
- It supports some TypeScript plugins but they are unofficial.
- Struggles with modern TypeScript features like generics or interfaces.
// esdoc: esdoc.json config
{
"source": "./src",
"destination": "./docs"
}
jsdoc is the standard for plain JavaScript.
- It ignores TypeScript syntax unless you strip types first.
- Relies entirely on JSDoc comments for type information.
// jsdoc: jsdoc.conf.json
{
"source": {
"include": ["src"],
"includePattern": ".+\\.js(doc|x)?$"
}
}
typedoc is built for TypeScript first.
- It reads your
tsconfig.jsonand understands interfaces, enums, and generics. - Can fall back to JavaScript but shines with
.tsfiles.
// typedoc: typedoc.json
{
"entryPoints": ["src/index.ts"],
"out": "docs"
}
⚙️ Configuration: Simple vs Complex
documentation uses CLI flags or a simple config file.
- You can run it with zero config for quick results.
- Custom themes require writing React components.
// documentation: .documentation.yml
project: My Library
version: 1.0.0
esdoc requires a JSON config file.
- You must specify plugins manually for features like coverage.
- Configuration options are limited compared to newer tools.
// esdoc: esdoc.json
{
"plugins": [{"name": "esdoc-coverage-plugin"}]
}
jsdoc uses a verbose JSON config.
- Setting up templates often requires installing separate packages.
- Highly flexible but can become hard to manage.
// jsdoc: jsdoc.conf.json
{
"templates": {
"cleverLinks": true,
"monospaceLinks": true
}
}
typedoc integrates with TypeScript config.
- It often needs no extra config if you have
tsconfig.json. - Options are extensive and cover edge cases in type reflection.
# typedoc: CLI with tsconfig
npx typedoc --options tsconfig.json
📝 Comment Syntax: JSDoc vs TSDoc
documentation uses standard JSDoc tags.
- Supports
@param,@returns, and@example. - Renders Markdown inside comments nicely.
// documentation: JSDoc comment
/**
* Adds two numbers.
* @param {number} a - First number
* @returns {number} Sum of a and b
*/
function add(a, b) { return a + b; }
esdoc uses JSDoc with some extensions.
- Supports
@typedefand@classheavily. - Markdown support is present but less consistent.
// esdoc: JSDoc comment
/**
* @class
*/
class User {
/**
* @type {string}
*/
name = '';
}
jsdoc relies strictly on JSDoc tags.
- You must define types manually since it cannot read TS types.
- Very verbose for complex type structures.
// jsdoc: Verbose JSDoc
/**
* @module math
*/
/**
* @function add
* @param {number} a
* @param {number} b
* @returns {number}
*/
export function add(a, b) { return a + b; }
typedoc supports TSDoc and JSDoc.
- It infers types from code, so comments can be shorter.
- Uses
@paramand@returnsbut reads signatures from TS.
// typedoc: TSDoc with inference
/**
* Adds two numbers.
* @param a - First number
* @param b - Second number
*/
export function add(a: number, b: number): number {
return a + b;
}
🛠️ Maintenance and Ecosystem
documentation is actively maintained.
- Regular updates fix bugs and improve output.
- Community is smaller than JSDoc but responsive.
# documentation: Check version
npx documentation --version
esdoc is no longer actively maintained.
- The repository has seen little activity in recent years.
- Security patches or feature updates are unlikely.
# esdoc: Warning
# No active maintenance schedule
jsdoc is stable and mature.
- Updates are infrequent because the tool is feature-complete.
- Huge ecosystem of third-party templates and plugins.
# jsdoc: Stable release cycle
npx jsdoc --version
typedoc is very active.
- Frequent releases to support new TypeScript versions.
- Essential for teams staying on the latest TS features.
# typedoc: Frequent updates
npx typedoc --version
📊 Summary: Key Differences
| Feature | documentation | esdoc | jsdoc | typedoc |
|---|---|---|---|---|
| Primary Language | JavaScript / Flow | ES6 JavaScript | JavaScript | TypeScript |
| Type Inference | Limited (Flow) | Minimal | None (Manual) | Full (TS) |
| Config Complexity | Low | Medium | High | Low (with TS) |
| Maintenance | Active | Inactive | Stable | Active |
| Best For | JS Libraries | Legacy ES6 | Large JS Apps | TS Libraries |
💡 The Big Picture
documentation is like a lightweight editor ✍️ — great for JavaScript projects that need clean docs without heavy setup. Ideal for open-source JS libraries.
esdoc is like an old map 🗺️ — it shows the way but is outdated. Avoid for new work; it does not handle modern type systems well.
jsdoc is like a sturdy filing cabinet 🗄️ — reliable and holds everything, but you must organize it manually. Best for established JavaScript codebases.
typedoc is like a smart assistant 🤖 — it reads your code and writes the docs for you based on types. The clear winner for TypeScript projects.
Final Thought: If you are using TypeScript, use typedoc. If you are using plain JavaScript, documentation offers a better developer experience than jsdoc for most cases, while jsdoc remains the safe choice for legacy compatibility. Avoid esdoc for new development.
How to Choose: documentation vs esdoc vs jsdoc vs typedoc
- documentation:
Choose
documentationif you write modern JavaScript or Flow and want a fast setup with good Markdown support. It handles JSDoc comments well but shines when you want a simpler config than JSDoc. It is a strong pick for libraries that prioritize ease of use over deep TypeScript integration. - esdoc:
Do not choose
esdocfor new projects. It is no longer actively maintained and lacks support for modern TypeScript features. Only use if maintaining a legacy system that already depends on it, and plan to migrate away soon. - jsdoc:
Choose
jsdocif you need maximum stability and a huge plugin ecosystem for plain JavaScript. It is the industry standard for JSDoc comments but requires more configuration to look modern. It works best for large, established JavaScript codebases. - typedoc:
Choose
typedocif your project is written in TypeScript. It automatically picks up types from your code, reducing the need for repetitive comments, and keeps docs in sync with your type definitions. It is the default choice for modern TypeScript libraries.
Popular Comparisons
README for documentation
The documentation system for modern JavaScript
:date: Current maintenance status
- Supports modern JavaScript: ES5, ES2017, JSX, Vue and Flow type annotations.
- Infers parameters, types, membership, and more. Write less documentation: let the computer write it for you.
- Integrates with GitHub to link directly from documentation to the code it refers to.
- Customizable output: HTML, JSON, Markdown, and more
Examples
Documentation
- Getting Started: start here
- Usage: how to use documentation.js
- Recipes: tricks for writing effective JSDoc docs
- Node API: documentation.js's self-generated documentation
- Configuring documentation.js
- FAQ
- Troubleshooting
- Theming: tips for theming documentation output in HTML
- See also: a list of projects similar to documentation.js
User Guide
Globally install documentation using the npm package manager:
$ npm install -g documentation
This installs a command called documentation in your path, that you can
point at JSDoc-annotated source code to generate
human-readable documentation. First, run documentation with the --help
option for help:
Usage:
# generate markdown docs for index.js and files it references
documentation build index.js -f md
# generate html docs for all files in src, and include links to source files in github
documentation build src/** -f html --github -o docs
# document index.js, ignoring any files it requires or imports
documentation build index.js -f md --shallow
# validate JSDoc syntax in util.js
documentation lint util.js
# update the API section of README.md with docs from index.js
documentation readme index.js --section=API
# build docs for all values exported by index.js
documentation build --document-exported index.js
# build html docs for a TypeScript project
documentation build index.ts --parse-extension ts -f html -o docs
Commands:
build [input..] build documentation
lint [input..] check for common style and uniformity mistakes
readme [input..] inject documentation into your README.md
Options:
--version Show version number [boolean]
--help Show help [boolean]
Contributing
We have plenty of issues that we'd love help with.
- Robust and complete
JSDocsupport, including typedefs. - Strong support for HTML and Markdown output
- Documentation coverage, statistics, and validation
documentation is an OPEN Open Source Project. This means that:
Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.