jsdoc

What is jsdoc?

JSDoc is a documentation generator for JavaScript. It parses comments in your source code with JSDoc tags and generates an HTML documentation website.

What are jsdoc's main functionalities?

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 ...
};

Other packages similar to jsdoc

typedoc

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

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.

README

JSDoc 3

An inline API documentation processor for JavaScript. JSDoc 3 is intended to be an upgrade to JsDoc Toolkit (JSDoc 2).

Want to contribute to JSDoc? Please read CONTRIBUTING.md.

Installation

Use git to clone the official JSDoc repository:

git clone https://github.com/jsdoc3/jsdoc.git

Alternatively, you can download a .zip file for the latest development version or a previous release.

You can also install JSDoc within a Node.js project's node_modules directory using npm. To install the latest development version, change directories to your Node.js project, then run the following command:

npm install git://github.com/jsdoc3/jsdoc.git

Or to install JSDoc globally:

npm install -g git://github.com/jsdoc3/jsdoc.git

Note: Although you can install JSDoc with npm, JSDoc does not currently run on Node.js.

Usage

This example assumes that your working directory is the JSDoc application base directory:

./jsdoc yourSourceCodeFile.js

For information about the supported command-line options, use the --help option.

./jsdoc --help

Generated documentation will appear in the folder specified by the --destination option, or in a folder named "out" by default.

Dependencies

JSDoc 3 uses the Mozilla Rhino engine, which requires Java. JSDoc 3 is known to work with version 1.6.0_24 of Java.

JSDoc 3 uses advanced features in Mozilla Rhino that are only available in or after version 1.7R3. In addition, JSDoc 3 requires several customizations to the standard Rhino distribution. The customized version of Rhino is included with JSDoc.

In rare cases, users may have their Java CLASSPATH configured to override the included Rhino and point to an older version of Rhino instead. If this is the case, simply correct the CLASSPATH to remove the older Rhino. (On OS X, you may need to remove the file ~/Library/Java/Extensions/js.jar.)

The version of Rhino distributed with JSDoc 3 can be found here: https://github.com/hegemonic/rhino

Debugging

Rhino is not always very friendly when it comes to reporting errors in JavaScript. Luckily, it comes with a full-on debugger included that can be much more useful than a simple stack trace. To invoke JSDoc with the debugger, run the following command on Windows:

jsdoc --debug

Or on OS X, Linux, and other POSIX-compliant systems:

./jsdoc --debug

If you can't get the short-form commands to work, try invoking Java directly:

java -cp lib/js.jar org.mozilla.javascript.tools.debugger.Main \
-debug -modules node_modules -modules rhino -modules lib -modules . \
jsdoc.js your/script.js

Note: --debug must be the first argument to the short-form command.

This will open a debugging window. Click Debug > Break on Exceptions, then click Run. If there is an error, you should see exactly where it is in the source code.

See Also

Project Documentation: http://usejsdoc.org/ (under development)
Project Documentation Source: https://github.com/jsdoc3/jsdoc3.github.com
JSDoc User's Group: http://groups.google.com/group/jsdoc-users
JSDoc 3 Ant Task: https://github.com/jannon/jsdoc3-ant-task
Project Announcements: http://twitter.com/jsdoc3

License

JSDoc 3 is copyright (c) 2011-2012 Michael Mathews [e-mail].

JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See the file LICENSE.md in this distribution for more details.

Changelog

3.2.2 (November 2013)

Bug fixes

• Addressed a regression in JSDoc 3.2.1 that could prevent a function declaration from shadowing a declaration with the same name in an outer scope. (#513)
• If a child class overrides a method in a parent class without documenting the overridden method, the method's documentation is now copied from the parent class. (#503)
• You can now use inline HTML tags in Markdown-formatted text. In addition, JSDoc now uses only the marked Markdown parser; the markdown-js parser has been removed. (#510)
• Type expressions can now include a much broader range of repeatable types. In addition, you can now use Closure Compiler's nullable and non-nullable modifiers with repeatable types. For example, the type expression ...!string (a repeatable, non-nullable string) is now parsed correctly. (#502)
• If a function accepts a parameter named prototype, the parameter is no longer renamed during parsing. (#505)
• If the list of input files includes relative paths, the paths are now resolved relative to the user's working directory. (a3d33842)