Speaking JavaScript

Chapter 29. JSDoc: Generating API Documentation

It is a common development problem: you have written JavaScript code that is to be used by others and need a nice-looking HTML documentation of its API. The de facto standard tool in the JavaScript world for generating API documentation is JSDoc.^[23] It is modeled after its Java analog, JavaDoc.

JSDoc takes JavaScript code with /** */ comments (normal block comments that start with an asterisk) and produces HTML documentation for it. For example, given the following code:

/** @namespace */
var util = {
    /**
     * Repeat <tt>str</tt> several times.
     * @param {string} str The string to repeat.
     * @param {number} [times=1] How many times to repeat the string.
     * @returns {string}
     */
    repeat: function(str, times) {
        if (times === undefined || times < 1) {
            times = 1;
        }
        return new Array(times+1).join(str);
    }
};

the generated HTML looks as shown in Figure 29-1 in a web browser.

Figure 29-1. HTML output produced by JSDoc.

The Readme on the JSDoc website explains how to install and call this tool.

The Basics of JSDoc

JSDoc is all about documenting entities (functions, methods, constructors, etc.). That is achieved via comments that precede the entities and start with /**.

Syntax

Let’s review the comment shown at the beginning:

/**
 * Repeat <tt>str</tt> several times.
 * @param {string} str The string to repeat.
 * @param {number} [times=1] How many times to ...