jsdoc

library1.0.3jsnpmunverified

JSDoc is an API documentation generator for JavaScript, enabling developers to create static HTML documentation websites directly from specially formatted comments within their source code. It supports modern JavaScript features, including ES2015 classes and modules, through its use of the Babylon (now @babel/parser) JavaScript parser. The project is actively maintained, with the current stable version being 4.0.5, and receives irregular but consistent updates focused on bug fixes, Node.js compatibility, and parser improvements. Key differentiators include its long-standing presence in the JavaScript ecosystem (since 1999), flexible configuration options via JSON or JavaScript files, and a rich community ecosystem offering numerous custom templates and build tool integrations (e.g., Grunt, Gulp). JSDoc allows for comprehensive annotation of functions, classes, modules, and parameters, facilitating improved code readability, maintainability, and providing rich IntelliSense support in modern IDEs.

devops serialization

npm install jsdoc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSDOC

jsdoc

devopsjavascriptv1.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsdoc

✓ This package is primarily a command-line interface (CLI) tool and is not typically imported programmatically as a library in standard JavaScript code. Instead, it's executed via the 'jsdoc' command.

JSDoc does not expose public JavaScript symbols for direct `import` or `require` in application code. Interaction is typically via shell commands, or through wrapper libraries like `jsdoc-api` for programmatic execution of its CLI functionalities.

Configuration

✓ jsdoc -c path/to/conf.json

✗ import config from 'jsdoc/conf'

Configuration is loaded by the CLI from a specified JSON or JavaScript file, not imported as a module. Since JSDoc 3.5.0, configuration can be a JavaScript file allowing for more dynamic settings.

Doclet (internal concept)

✓ N/A (internal data structure)

While JSDoc processes code into 'doclets' (JSON objects representing documented symbols), these are internal to JSDoc's operation. External tools like `jsdoc-to-markdown` or `jsdoc-api` might expose ways to access these processed data structures, but JSDoc itself does not provide a direct `import` for its internal doclet representation.

This quickstart demonstrates how to install JSDoc locally, add JSDoc comments to a JavaScript class, and generate HTML documentation into a './docs' directory using an npm script.

npm install --save-dev jsdoc // my-module.js /** * Represents a simple calculator. * @class */ class Calculator { /** * Adds two numbers. * @param {number} a - The first number. * @param {number} b - The second number. * @returns {number} The sum of a and b. */ add(a, b) { return a + b; } /** * Subtracts two numbers. * @param {number} x - The number to subtract from. * @param {number} y - The number to subtract. * @returns {number} The difference of x and y. */ subtract(x, y) { return x - y; } } module.exports = Calculator; // package.json (add this script) // { // "scripts": { // "generate-docs": "jsdoc my-module.js -d ./docs" // } // } // To run: npm run generate-docs

jsdoc --version

Debug

Known issues

breakingJSDoc 3.5.0 switched to the Babylon (now @babel/parser) JavaScript parser, significantly enhancing support for modern JavaScript and JSX syntax. This change might alter how some edge cases or previously unsupported syntax were handled, potentially leading to different parsing results or requiring adjustments for custom plugins.

fix

Ensure your JSDoc plugins and templates are compatible with the updated parser. Review generated documentation for any unexpected changes, especially for ES2015+ features. If encountering issues, check the JSDoc changelog or GitHub issues for known parser-related incompatibilities.

affects: >=3.5.0

breakingJSDoc 3.5.0 introduced support for using JavaScript files for configuration, alongside JSON. While JSON remains supported, JavaScript configuration offers greater flexibility but changes the expected file type if you switch.

fix

If migrating an older configuration, ensure your configuration file is either valid JSON or correctly formatted JavaScript that exports the configuration object. Update your JSDoc command-line arguments (e.g., `-c`) if the filename or extension changes.

affects: >=3.5.0

gotchaJSDoc requires Node.js 12.0.0 or later for version 4.x. Older versions of JSDoc had specific Node.js compatibility fixes (e.g., 3.5.5 fixed incompatibility with Node.js 8.5.0, 4.0.4 fixed with Node.js 23). Running with an unsupported Node.js version can lead to errors or unexpected behavior.

fix

Always check the `engines.node` field in `package.json` or the official documentation (`jsdoc.app`) for the required Node.js version for your specific JSDoc release. Update your Node.js environment if necessary.

affects: All versions

gotchaBy default, JSDoc only recognizes comments starting with `/**`. Comments beginning with `/*`, `/***`, or more than three asterisks are ignored. This is an intentional feature for suppressing parsing.

fix

Ensure all comments intended for documentation strictly begin with `/**`. Avoid extra asterisks or single-asterisk block comments for JSDoc-parsed blocks.

affects: All versions

gotchaThe `@hideconstructor` tag with the default template had an issue in earlier 3.x versions, where it might not have correctly hidden the constructor documentation.

fix

Upgrade to JSDoc 3.5.2 or later to ensure the `@hideconstructor` tag functions as expected with the default template. If using a custom template, verify its implementation of this tag.

affects: <3.5.2

Errors

Common errors & fixes

Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

Attempting to install JSDoc globally without sufficient permissions on Unix-like systems.

fix

Use `npm install -g jsdoc --force` or fix npm permissions using `sudo npm install -g jsdoc` (less recommended due to security implications, better to fix npm's directory permissions). Refer to npm's documentation on 'resolving EACCES permissions errors'.

command not found: jsdoc

JSDoc was installed locally (e.g., `npm install --save-dev jsdoc`) but is being invoked without specifying its local path or running via an npm script.

fix

If installed locally, run it using `./node_modules/.bin/jsdoc yourJavaScriptFile.js` or define an npm script in `package.json` like `"docs": "jsdoc -c jsdoc.json"` and run with `npm run docs`.

Parsing error: Unexpected token ... (related to ES2015+ syntax)

Using an older version of JSDoc (prior to 3.5.0) that did not fully support modern JavaScript syntax (e.g., classes, arrow functions, async/await).

fix

Upgrade JSDoc to version 3.5.0 or newer. This version introduced the Babylon parser, providing robust support for contemporary JavaScript and JSX.

JSDoc did not generate documentation for some comments.

Comments might not start with exactly `/**`, or are placed incorrectly, leading JSDoc to ignore them. Earlier versions also had issues with comments at the end of files or specific namepath formats.

fix

Ensure all desired JSDoc blocks start with `/**`. Check for extra asterisks (`/***`) or single-asterisk block comments (`/*`). Verify that comments are immediately preceding the code they document. Upgrade to JSDoc 3.5.3 or later for fixes related to comment parsing in specific scenarios (e.g., end-of-file comments, specific namepaths).

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/jsdoc/jsdoc ↗

packagehttps://www.npmjs.com/package/jsdoc ↗

homepagehttps://jsdoc.app ↗