JSDoc

Common errors

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

  cause 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

  cause 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)

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

  cause 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).

Warnings

• breaking JSDoc 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.
• breaking JSDoc 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.
• gotcha JSDoc 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.
• gotcha By 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.
• gotcha The `@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.

Install

• npm install jsdoc npm
• yarn add jsdoc yarn
• pnpm add jsdoc pnpm

Imports

• 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
  wrong:

  import config from 'jsdoc/conf'

  correct:

  jsdoc -c path/to/conf.json

  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.

Quickstart

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