Maintainable JavaScript

Chapter 18. Documentation

All engineers would rather be writing code than documentation, which is precisely why tools that autogenerate documentation from code are so popular. The trend really began with Javadoc, the tool that automatically creates documentation for Java, and continued into other languages such as JavaScript.

There is a large (and growing) number of documentation generators that work with JavaScript. Some are general-purpose documentation generators that work with any language; others are JavaScript-specific. As with minifiers, the choice of documentation generator is more of a preference than anything else. This chapter covers a few popular choices; there are many more out there. See Appendix B for a full list of alternatives.

JSDoc Toolkit

JSDoc Toolkit is perhaps the most commonly used JavaScript documentation generator. An evolution of the original JSDoc released in 2011, JSDoc Toolkit is used by Google and SproutCore and is often credited with starting the trend of writing JavaScript-specific documentation generators. It uses the same basic syntax as Javadoc, with special multiline comments indicating documentation information. For example:

/**
 * @namespace The main application object.
 */
var MyApplication = {

    /**
     * Adds two numbers together.
     * @param {int} num1 The first number.
     * @param {int} num2 The second number.
     * @returns {int} The sum of the two numbers.
     * @static
     */
    add: function (num1, num2) {
        return num1 + num2;
    }
}

Any object for which there is no constructor ...