JSDoc Documentation

The @memberof tag identifies a symbol (like a function, variable, or property) as a member of a parent symbol (such as a namespace or class).

By default, @memberof documents symbols as static members. To document inner or instance members, you can either use scoping punctuation in the namepath or use the @inner or @instance tags.

Syntax:

• @memberof <parentNamepath>
• @memberof! <parentNamepath> (The ! version forces the symbol to belong to the specified parent, even if JSDoc detects a different parent.)

/** @namespace */
var Tools = {};

/** @memberof Tools */
var hammer = function() {
};

Tools.hammer = hammer;

If you provide multiple tags that imply different kinds (for example, using both @module and @kind constant), JSDoc resolves the conflict by using the last tag encountered in the documentation block.

/**
 * This will show up as a constant because @kind constant comes last.
 * @module myModule
 * @kind constant
 */

/**
 * This will show up as a module because @module comes last.
 * @kind constant
 * @module myModule
 */

The @abstract tag is used to identify members (methods or properties) that are intended to be implemented or overridden by any object that inherits from the parent class. It serves as a documentation signal that the base implementation is incomplete or serves only as a template, often throwing an error if called directly.

/**
 * Parent class with abstract method
 */
function Parent() {}

/**
 * @abstract
 * @return {boolean}
 */
Parent.prototype.method = function() {
    throw new Error('must be implemented by subclass!');
};

/**
 * Child class that implements the method
 * @augments Parent
 */
function Child() {}

/**
 * @return {boolean}
 */
Child.prototype.method = function() {
    return true;
};

If you want to document an interface without writing actual implementation code, you can use "virtual comments." This allows you to define the structure of an interface (its methods and properties) purely through JSDoc annotations.

To do this:

1. Use @interface [Name] on a comment block to declare the interface.
2. Use @function and @name [InterfaceName]#[memberName] to define the members of that virtual interface.

/**
 * Interface for classes that represent a color.
 *
 * @interface Color
 */

/**
 * Get the color as an array of red, green, and blue values.
 *
 * @function
 * @name Color#rgb
 * @returns {Array<number>} An array containing the red, green, and blue values.
 */

The @constructs tag is used when defining a class via an object literal (often in conjunction with the @lends tag) to specify which function serves as the constructor for that class.

If you are using @lends to link an object literal to a class, you can use @constructs without an argument. If you are not using @lends, you must provide the name of the class as an argument to the tag (e.g., @constructs ClassName).

// Example with @lends (no name required)
var Person = makeClass(
    /** @lends Person.prototype */
    {
        /** @constructs */
        initialize: function(name) {
            this.name = name;
        }
    }
);

// Example without @lends (name required)
makeClass('Menu',
    /**
     * @constructs Menu
     */
    function (items) { },
    {}
);

JSDoc uses specific namepath conventions to distinguish between module-private (inner) members and exported (static) members.

Inner vs. Static Members

• Inner Members: Variables or functions that are not exported are treated as module-private. They use the tilde (~) separator. Example: module:myModule~foo.
• Static Members: Symbols exported via module.exports, exports, or this are treated as static members of the module. They use the dot (.) separator. Example: module:myModule.bar.

Export Patterns

JSDoc automatically infers static membership when symbols are assigned to:

1. module.exports
2. exports
3. this (common in constructor functions/classes)

/** @module myModule */

/** will be module:myModule~foo (inner) */
var foo = 1;

/** will be module:myModule.bar (static) */
var bar = function() {};

JSDoc automatically recognizes exports in standard Node.js and CommonJS environments. You do not need to use the @exports tag if you are using the exports object or the module.exports property.

/**
 * A module that says hello!
 * @module hello/world
 */

/** Say hello. */
exports.sayHello = function() {
    return 'Hello world';
};

Use the @ignore tag to prevent a symbol from appearing in your generated documentation. This tag takes precedence over all other JSDoc tags.

Behavior by type:

• @class or @module: Applying @ignore to a class or module will omit the entire entity from the documentation.
• @namespace: If you ignore a namespace, you must also apply the @ignore tag to all child classes and namespaces within it. If you do not, the children will still appear in the documentation, but they will have incomplete/broken names.

/**
 * @class
 * @ignore
 */
function Jacket() {
    /** The jacket's color. */
    this.color = null;
}

JSDoc 3 plugins allow you to control the parsing process through three primary mechanisms:

1. Event Handlers: Register handlers for specific named events fired by JSDoc (e.g., newDoclet, symbolFound).
2. Tag Definitions: Add new tags to the JSDoc tag dictionary to modify doclets when specific tags are encountered in comments.
3. Node Visitors: Process every node in the Abstract Syntax Tree (AST) to document undocumented code or modify comments.

When using a namepath to refer to a module from a different JSDoc comment, you must prefix the module name with module:.

For example, to link to the my/shirt module from the my/pants module using the @see tag, use module:my/shirt.

This prefix also applies to the namepaths of members within a module. If a module my/pants exports a class Jeans with an instance method hem, the full namepath for that method is module:my/pants.Jeans#hem.

/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */