{"id":14648,"library":"jsdoc","title":"JSDoc","description":"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.","status":"active","version":"4.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/jsdoc/jsdoc","tags":["javascript","documentation"],"install":[{"cmd":"npm install jsdoc","lang":"bash","label":"npm"},{"cmd":"yarn add jsdoc","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsdoc","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"jsdoc","correct":"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."},{"note":"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.","wrong":"import config from 'jsdoc/conf'","symbol":"Configuration","correct":"jsdoc -c path/to/conf.json"},{"note":"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.","symbol":"Doclet (internal concept)","correct":"N/A (internal data structure)"}],"quickstart":{"code":"npm install --save-dev jsdoc\n\n// my-module.js\n/**\n * Represents a simple calculator.\n * @class\n */\nclass Calculator {\n  /**\n   * Adds two numbers.\n   * @param {number} a - The first number.\n   * @param {number} b - The second number.\n   * @returns {number} The sum of a and b.\n   */\n  add(a, b) {\n    return a + b;\n  }\n\n  /**\n   * Subtracts two numbers.\n   * @param {number} x - The number to subtract from.\n   * @param {number} y - The number to subtract.\n   * @returns {number} The difference of x and y.\n   */\n  subtract(x, y) {\n    return x - y;\n  }\n}\n\nmodule.exports = Calculator;\n\n// package.json (add this script)\n// {\n//   \"scripts\": {\n//     \"generate-docs\": \"jsdoc my-module.js -d ./docs\"\n//   }\n// }\n\n// To run: npm run generate-docs\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.5.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all comments intended for documentation strictly begin with `/**`. Avoid extra asterisks or single-asterisk block comments for JSDoc-parsed blocks.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.5.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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'.","cause":"Attempting to install JSDoc globally without sufficient permissions on Unix-like systems.","error":"Error: EACCES: permission denied, access '/usr/local/lib/node_modules'"},{"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`.","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.","error":"command not found: jsdoc"},{"fix":"Upgrade JSDoc to version 3.5.0 or newer. This version introduced the Babylon parser, providing robust support for contemporary JavaScript and JSX.","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).","error":"Parsing error: Unexpected token ... (related to ES2015+ syntax)"},{"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).","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.","error":"JSDoc did not generate documentation for some comments."}],"ecosystem":"npm"}