Es ist ein häufiges Entwicklungsproblem: Sie haben JavaScript-Code geschrieben, der von anderen verwendet werden soll, und benötigen eine ansprechend aussehende HTML-Dokumentation seiner API. Das De-facto-Standardwerkzeug in der JavaScript-Welt für die Generierung von API-Dokumentationen ist JSDoc.^[23] Es ist seinem Java-Analogon, JavaDoc, nachempfunden.

JSDoc nimmt JavaScript-Code mit /** */-Kommentaren (normale Blockkommentare, die mit einem Sternchen beginnen) und erzeugt daraus eine HTML-Dokumentation. Zum Beispiel, gegeben den folgenden 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);
    }
};

sieht die generierte HTML-Ausgabe wie in Abbildung 29-1 in einem Webbrowser aus.

Abbildung 29-1. HTML-Ausgabe von JSDoc.

Das Readme auf der JSDoc-Website erklärt, wie dieses Werkzeug installiert und aufgerufen wird.

/**
 * 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}
 */

/**
 * @param {String} name
 * @returns {Object}
 */
function getPerson(name) {
}

function getPerson(/**String*/ name) /**Object*/ {
}

/**
 * A class for managing persons.
 * @constructor
 */
function Person(name) {
}

/**
 * A class for managing persons.
 * @class
 */
var Person = makeClass(
    /** @lends Person# */
    {
        say: function(message) {
            return 'This person says: ' + message;
        }
    }
);

var Person = makeClass(
    /** @lends Person# */
    {
        /**
         * A class for managing persons.
         * @constructs
         */
        initialize: function(name) {
            this.name = name;
        },
        say: function(message) {
            return this.name + ' says: ' + message;
        }
    }
);

var Person = makeClass({
        /**
         * A class for managing persons.
         * @constructs Person
         */
        initialize: function(name) {
            this.name = name;
        },
        /** @memberof Person# */
        say: function(message) {
            return this.name + ' says: ' + message;
        }
    }
);