It is a JSDoc.^[] 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:

the generated HTML looks as shown in in a web browser.

Figure 29-1. HTML output produced by JSDoc.

The 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 /**.

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 repeat the string.
 * @returns {string}
 */

This demonstrates some of the JSDoc syntax, which consists of thefollowing pieces:

• JSDoc comment
• This is a JavaScript block comment whose first character is an asterisk. This creates the illusion that the token /** starts such a comment.
• Tags
• You structure comments by starting lines with tags, keywords that are prefixed with an @ symbol. @param is an example in the preceding code.
• HTML
• You can freely use HTML in JSDoc comments. For example, <tt> displays a word in a monospaced font.
• Type annotations
• You can document the type of an entity via a type name in braces. Variations include:

• Single type: @param {string} name
• Multiple types: @param {string|number} idCode
• Arrays of a type: @param {string[]} names

• Namepaths
• Inside JSDoc comments, so-called namepaths are used to refer to entities. The syntax of such paths is as follows:

myFunction
MyClass
MyClass.staticMember
MyClass#instanceMember

Classes are usually (implemented by) constructors. Static members are, for example, properties of constructors. JSDoc has a broad definition of instance member. It means everything that can be accessed via an instance. Therefore, instance members include instance properties and prototype properties.

Naming Types

The types of

Following are the basic metadata tags:

• @fileOverview description
• Marks a JSDoc comment that describes thewhole file. For example:

/**
 * @fileOverview Various tool functions.
 * @author <a href="mailto:jd@example.com">John Doe</a>
 * @version 3.1.2
 */

• @author
• Refers to who has written the entity being documented.
• @deprecated
• Indicates that the entity is not supported anymore. It is a good practice to document what to use instead.
• @example
• Contains a code example illustrating how the given entityshould be used:

/**
 * @example
 * var str = 'abc';
 * console.log(repeat(str, 3)); // abcabcabc
 */

Basic tags for linking are as follows:

• @see
• Points to a related resource:

/**
 * @see MyConstructor#myMethod
 * @see The <a href="http://example.com">Example Project</a>.
 */

• Works like @see, but can be used inside other tags.
• @requires resourceDescription
• Indicates a resource that the documented entityneeds. The resource description is either a namepath or a naturallanguage description.

• @version versionNumber
• Indicates the version of the documentedentity. For example:

@version 10.3.1

• @since versionNumber
• Indicates since which version the documentedentity has been available. For example:

Documenting Functions and Methods

For functions and methods, you can document parameters, return values, and exceptions they may throw:

• @param {paramType} paramName description
• Describes the parameter whose name is paramName. Type and description are optional. Here are some examples:

@param str The string to repeat.
@param {string} str
@param {string} str The string to repeat.

Advanced features:

• Optional parameter:

@param {number} [times] The number of times is optional.

• Optional parameter with default value:

@param {number} [times=1] The number of times is optional.

• @returns {returnType} description
• Describes the return value of the function or method. Either type or description can be omitted.
• @throws {exceptionType} description
• Describes an exception that might be thrown during the execution of the function or method. Either type or description can be omitted.

There are

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

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

Documenting Variables, Parameters, and Instance Properties

The following tags

• @type {typeName}
• What type does the documented variable have? For example:

/** @type {number} */
var carCounter = 0;

This tag can also be used to document the return type of functions, but @returns is preferable in this case.

• @constant
• A flag that indicates that the documented variable has a constant value.

• @property {propType} propKey description
• Document an instance property in the constructor comment. For example:

/**
 * @constructor
 * @property {string} name The name of the person.
 */
function Person(name) 
    this.name = name;
}

Alternatively, instance properties can be documented as follows:

/**
 * @class
 */
function Person(name) {
    /**
     * The name of the person.
     * @type {string}
     */
    this.name = name;
}

Which one of those styles to use is a matter of personal preference.

• @default defaultValue
• What is the default value of a parameter or instance property?For example:

/** @constructor */
function Page(title) {
    /**
     * @default 'Untitled'
     this.title = title || 'Untitled';
}

JSDoc distinguishes The former concept is more like a type, while a constructor is one way of implementing a class.JavaScript’s built-in means for defining classes are limited, which is why there are many APIs that help with this task. These APIs differ, often radically, so you have to help JSDoc with figuring out what is going on. The following tags let you do that:

• @constructor
• Marks a function as a constructor.
• @class
• Marks a variable or a function as a class. In the latter case, @class is a synonym for @constructor.
• @constructs
• Records that a method sets up the instance data. If such a method exists, the class is documented there.
• @lends namePath
• Specifies to which class the following object literal contributes. There are two ways of contributing.

• @lends Person#: The object literal contributes instance members to Person.
• @lends Person: The object literal contributes static members to Person.

• @memberof parentNamePath
• The documented entity is a member of the specified object. @lends MyClass#, applied to an object literal, has the same effect as marking each property of that literal with @memberof MyClass#.

The most common ways of defining a class are: via a constructor function, via an object literal, and via an object literal that has an @constructs method.

To define a class via a constructor function, you must mark the constructor function; otherwise, it will not be documented as a class. Capitalization alone does not mark a function as a constructor:

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

Defining a Class via an Object Literal

To define a class via an object literal, you need two markers. First, you need to tell JSDoc that a given variable holds a class. Second, you need to mark an object literal as defining a class. You do the latter via the @lends tag:

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

If an object literal has an @constructs method, you need to tell JSDoc about it, so that it can find the documentation for the instance properties. The documentation of the class moves to that method:

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

If you omit the @lends, you must specify which class the methods belong to:

Subclassing

JavaScript has no built-in support for subclassing. When you subclass in your code (be it manually, be it via a library), you have to tell JSDoc what is going on:

• @extends namePath
• Indicates that the documented class is thesubclass of another one. For example:

/**
 * @constructor
 * @extends Person
 */
function Programmer(name) {
    Person.call(this, name);
    ...
}
// Remaining code for subclassing omitted

Other Useful Tags

All of these JSDoc website:

• Modularity: @module, @exports, @namespace
• Custom types (for virtual entities such as callbacks, whose signature you can document): @typedef, @callback
• Various kinds of objects: @mixin,

^[] The JSDoc website is the main source of this chapter; some examples are borrowed from it.