JSDoc is a documentation generator for JavaScript. It parses comments in your source code with JSDoc tags and generates an HTML documentation website.
Generating API documentation
This code sample shows how to use JSDoc comments to document a constructor function for a book. When JSDoc processes this, it will generate documentation for the Book function, including its parameters and their types.
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
this.title = title;
this.author = author;
}Documenting a class and its methods
This code sample demonstrates how to document a class and its constructor, as well as a method within the class. JSDoc will generate documentation for the Point class, its constructor, and the getDistanceTo method, including parameter and return types.
/**
* Class representing a point.
*/
class Point {
/**
* Create a point.
* @param {number} x - The x value.
* @param {number} y - The y value.
*/
constructor(x, y) {
this.x = x;
this.y = y;
}
/**
* Get the distance from this point to another point.
* @param {Point} point - The point to get the distance to.
* @returns {number} The distance.
*/
getDistanceTo(point) {
// ... implementation ...
}
}Documenting module exports
This code sample shows how to document a module and a function that it exports. JSDoc will generate documentation for the module and the exported function, including the function's parameters and return value.
/**
* @module myModule
*/
/**
* A function that does something.
* @param {number} input - The input number.
* @returns {number} The result.
*/
exports.myFunction = function(input) {
// ... implementation ...
};TypeDoc is a documentation generator that is similar to JSDoc but is specifically designed for TypeScript projects. It reads TypeScript source files and produces API documentation from the comments. Compared to JSDoc, TypeDoc is more suited for TypeScript due to its understanding of TypeScript-specific features.
ESDoc is a good documentation generator for JavaScript (ES6) projects. It focuses on the ECMAScript 2015 (ES6) syntax and has features like coverage reporting, which shows how much of your code is documented. ESDoc also supports plugin architecture, allowing for additional functionality to be added.
An API documentation generator for JavaScript.
Want to contribute to JSDoc? Please read CONTRIBUTING.md.
JSDoc supports Node.js 4.2.0 and later. You can install JSDoc in your project's
node_modules folder, or you can install it globally.
To install the latest version available on NPM:
npm install jsdoc
To install the latest development version:
npm install git+https://github.com/jsdoc3/jsdoc.git
If you installed JSDoc locally, the JSDoc command-line tool is available in
./node_modules/.bin. To generate documentation for the file
yourJavaScriptFile.js:
./node_modules/.bin/jsdoc yourJavaScriptFile.js
Or if you installed JSDoc globally, simply run the jsdoc command:
jsdoc yourJavaScriptFile.js
By default, the generated documentation is saved in a directory named out. You
can use the --destination (-d) option to specify another directory.
Run jsdoc --help for a complete list of command-line options.
The JSDoc community has created numerous templates and other tools to help you generate and customize your documentation. Here are just a few:
jsdoc to Stack
Overflow.JSDoc 3 is copyright (c) 2011-present Michael Mathews micmath@gmail.com and the contributors to JSDoc.
JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See
the file LICENSE.md in this distribution for more details.
3.5.0 (July 2017)
JSDoc now uses the Babylon JavaScript parser, which means that JSDoc can parse any JavaScript or JSX file that is supported by the Babel compiler. For example, JSDoc can now parse JavaScript files that include all of the following language features:
+ [Decorators](https://github.com/tc39/proposal-decorators)
+ [Public and private class fields](https://github.com/tc39/proposal-class-fields)
+ [Asynchronous iterators](https://github.com/tc39/proposal-async-iteration)
+ [Dynamic `import()`](https://github.com/tc39/proposal-dynamic-import)
+ [Optional chaining](https://github.com/tc39/proposal-optional-chaining)
You can now use a JavaScript file to configure JSDoc. The JavaScript file must be a CommonJS module that exports a single configuration object. See the documentation for details and examples.
Fixed multiple issues with documenting ES2015 classes and modules. See "Bug fixes" for details.
JSDoc now requires Node.js 4.2.0 or later.
Note: Third-party templates may not support these new tags.
@async tag to indicate that a
function is asynchronous (that is, that it was declared with the syntax async function foo() {}).
In general, you do not need to use this tag, because JSDoc autodetects asynchronous functions.
(#1188)@generator tag to indicate
that a function is a generator function. In general, you do not need to use this tag, because JSDoc
autodetects generator functions. (#1158)@hideconstructor tag to
tell JSDoc to hide a class's constructor from the documentation. (#952)@package tag to indicate that a
symbol is package-private. (#962)@yields tag to document the
value that is yielded by a generator function. (#1388)async function foo() {}), and JSDoc autodetects when a function is asynchronous. (#1188)jsdocCommentFound and symbolFound events, the event now includes a columnno
property indicating the column number on which the comment or symbol was found. (#1362)sourceType configuration option to control how JavaScript files are
parsed. The default value is module. Set the value to script to suppress implied strict mode;
this setting will also prevent you from using ES2015 modules. (#1210)recurseDepth configuration option to control how many levels deep JSDoc
will recursively search for files. The default value is 10. (#1340)plugins/ or templates/ directory, JSDoc can now
discover plugins and templates in other directories. (#1081, #1308)@author tag does not have a value. (#1289)process.exit() when exiting. (#1287)FAQs
An API documentation generator for JavaScript.
The npm package jsdoc receives a total of 858,338 weekly downloads. As such, jsdoc popularity was classified as popular.
We found that jsdoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.