ES 2015 Classes

JSDoc 3 makes it easy to document classes that follow the ECMAScript 2015 specification. You don't need to use tags such as @class and @constructor with ES 2015 classes—JSDoc automatically identifies classes and their constructors simply by parsing your code. ES 2015 classes are supported in JSDoc 3.4.0 and later.

Documenting a simple class

The following example shows how to document a simple class with a constructor, two instance methods, and one static method:

Simple ES 2015 class

/** Class representing a point. */

class Point {

/**

* Create a point.

* @param {number} x - The x value.

* @param {number} y - The y value.

*/

constructor(x, y) {

// ...

}

/**

* Get the x value.

* @return {number} The x value.

*/

getX() {

// ...

}

/**

* Get the y value.

* @return {number} The y value.

*/

getY() {

// ...

}

/**

* Convert a string containing two comma-separated numbers into a point.

* @param {string} str - The string containing two comma-separated numbers.

* @return {Point} A Point object.

*/

static fromString(str) {

// ...

}

}

You can also document classes that are defined in a class expression, which assigns the class to a variable or constant:

ES 2015 class expression

/** Class representing a point. */

const Point = class {

// and so on

}

Extending classes

When you use the extends keyword to extend an existing class, you also need to tell JSDoc which class you're extending. You do this with the @augments (or @extends) tag.

For example, to extend the Point class shown above:

Extending an ES 2015 class

/**

* Class representing a dot.

* @extends Point

*/

class Dot extends Point {

/**

* Create a dot.

* @param {number} x - The x value.

* @param {number} y - The y value.

* @param {number} width - The width of the dot, in pixels.

*/

constructor(x, y, width) {

// ...

}

/**

* Get the dot's width.

* @return {number} The dot's width, in pixels.

*/

getWidth() {

// ...

}

}

ES 2015 Modules

JSDoc 3 makes it possible to document modules that follow the ECMAScript 2015 specification. ES 2015 modules are supported in JSDoc 3.4.0 and later.

Module identifiers

When you document an ES 2015 module, you'll use a @module tag to document the identifier for the module. For example, if users load the module by calling import * as myShirt from 'my/shirt', you'll write a JSDoc comment that contains the tag @module my/shirt.

If you use the @module tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

When you use a JSDoc namepath to refer to a module from another JSDoc comment, you must add the prefix module:. For example, if you want the documentation for the module my/pants to link to the module my/shirt, you could use the @see tag to document my/pants as follows:

/**

* Pants module.

* @module my/pants

* @see module:my/shirt

*/

Similarly, the namepath for each member of the module will start with module:, followed by the module name. For example, if your my/pants module exports a Jeans class, and Jeans has an instance method named hem, the instance method's longname is module:my/pants.Jeans#hem.

Exported values

The following example shows how to document different kinds of exported values in an ES 2015 module. In most cases, you can simply add a JSDoc comment to the export statement that defines the exported value. If you are exporting a value under another name, you can document the exported value within its export block.

Documenting values exported by a module

/** @module color/mixer */

/** The name of the module. */

export const name = 'mixer';

/** The most recent blended color. */

export var lastColor = null;

/**

* Blend two colors together.

* @param {string} color1 - The first color, in hexadecimal format.

* @param {string} color2 - The second color, in hexadecimal format.

* @return {string} The blended color.

*/

export function blend(color1, color2) {}

// convert color to array of RGB values (0-255)

function rgbify(color) {}

export {

/**

* Get the red, green, and blue values of a color.

* @function

* @param {string} color - A color, in hexadecimal format.

* @returns {Array.<number>} An array of the red, green, and blue values,

* each ranging from 0 to 255.

*/

rgbify as toRgb

}

CommonJS Modules

Overview

To help you document CommonJS modules, JSDoc 3 understands many of the conventions used in the CommonJS specification (for example, adding properties to the exports object). In addition, JSDoc recognizes the conventions of Node.js modules, which extend the CommonJS standard (for example, assigning a value to module.exports). Depending on the coding conventions you follow, you may need to provide some additional tags to help JSDoc understand your code.

This page explains how to document CommonJS and Node.js modules that use several different coding conventions. If you're documenting Asynchronous Module Definition (AMD) modules (also known as "RequireJS modules"), see AMD Modules.

Module identifiers

In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that contains a @module tag. The @module tag's value should be the module identifier that's passed to the require() function. For example, if users load the module by calling require('my/shirt'), your JSDoc comment would contain the tag @module my/shirt.

If you use the @module tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

When you use a JSDoc namepath to refer to a module from another JSDoc comment, you must add the prefix module:. For example, if you want the documentation for the module my/pants to link to the module my/shirt, you could use the @see tag to document my/pants as follows:

/**

* Pants module.

* @module my/pants

* @see module:my/shirt

*/

Similarly, the namepath for each member of the module will start with module:, followed by the module name. For example, if your my/pants module exports a Jeans constructor, and Jeans has an instance method named hem, the instance method's longname is module:my/pants.Jeans#hem.

Properties of the 'exports' object

It's easiest to document symbols that are directly assigned to a property of the exports object. JSDoc will automatically recognize that the module exports these symbols.

In the following example, the my/shirt module exports the methods button and unbutton. JSDoc will automatically detect that the module exports these methods.

Methods added to the exports object

/**

* Shirt module.

* @module my/shirt

*/

/** Button the shirt. */

exports.button = function() {

// ...

};

/** Unbutton the shirt. */

exports.unbutton = function() {

// ...

};

Values assigned to local variables

In some cases, an exported symbol may be assigned to a local variable before it's added to the exports object. For example, if your module exports a wash method, and the module itself often calls the wash method, you might write the module as follows:

Method assigned to a local variable and added to the exports object

/**

* Shirt module.

* @module my/shirt

*/

/** Wash the shirt. */

var wash = exports.wash = function() {

// ...

};

In this case, JSDoc will not automatically document wash as an exported method, because the JSDoc comment appears immediately before the local variable wash rather than exports.wash. One solution is to add an @alias tag that defines the correct longname for the method. In this case, the method is a static member of the module my/shirt, so the correct longname is module:my/shirt.wash:

Longname defined in an @alias tag

/**

* Shirt module.

* @module my/shirt

*/

/**

* Wash the shirt.

* @alias module:my/shirt.wash

*/

var wash = exports.wash = function() {

// ...

};

Another solution is to move the method's JSDoc comment so it comes immediately before exports.wash. This change allows JSDoc to detect that wash is exported by the module my/shirt:

JSDoc comment immediately before exports.wash

/**

* Shirt module.

* @module my/shirt

*/

var wash =

/** Wash the shirt. */

exports.wash = function() {

// ...

};

Values assigned to 'module.exports'

In a Node.js module, you can assign a value directly to module.exports. This section explains how to document different types of values when they are assigned to module.exports.

Object literal assigned to 'module.exports'

If a module assigns an object literal to module.exports. JSDoc automatically recognizes that the module exports only this value. In addition, JSDoc automatically sets the correct longname for each property:

Object literal assigned to module.exports

/**

* Color mixer.

* @module color/mixer

*/

module.exports = {

/**

* Blend two colors together.

* @param {string} color1 - The first color, in hexadecimal format.

* @param {string} color2 - The second color, in hexadecimal format.

* @return {string} The blended color.

*/

blend: function(color1, color2) {

// ...

},

/**

* Darken a color by the given percentage.

* @param {string} color - The color, in hexadecimal format.

* @param {number} percent - The percentage, ranging from 0 to 100.

* @return {string} The darkened color.

*/

darken: function(color, percent) {

// ..

}

};

You can also use this pattern if you add properties to module.exports outside of the object literal:

Assignment to module.exports followed by property definition

/**

* Color mixer.

* @module color/mixer

*/

module.exports = {

/**

* Blend two colors together.

* @param {string} color1 - The first color, in hexadecimal format.

* @param {string} color2 - The second color, in hexadecimal format.

* @return {string} The blended color.

*/

blend: function(color1, color2) {

// ...

}

};

/**

* Darken a color by the given percentage.

* @param {string} color - The color, in hexadecimal format.

* @param {number} percent - The percentage, ranging from 0 to 100.

* @return {string} The darkened color.

*/

module.exports.darken = function(color, percent) {

// ..

};

Function assigned to 'module.exports'

If you assign a function to module.exports, JSDoc will automatically set the correct longname for the function:

Function assigned to 'module.exports'

/**

* Color mixer.

* @module color/mixer

*/

/**

* Blend two colors together.

* @param {string} color1 - The first color, in hexadecimal format.

* @param {string} color2 - The second color, in hexadecimal format.

* @return {string} The blended color.

*/

module.exports = function(color1, color2) {

// ...

};

The same pattern works for constructor functions:

Constructor assigned to 'module.exports'

/**

* Color mixer.

* @module color/mixer

*/

/** Create a color mixer. */

module.exports = function ColorMixer() {

// ...

};

String, number, or boolean assigned to 'module.exports'

For value types (strings, numbers, and booleans) assigned to module.exports, you must document the exported value's type by using the @type tag in the same JSDoc comment as the @module tag:

String assigned to module.exports

/**

* Module representing the word of the day.

* @module wotd

* @type {string}

*/

module.exports = 'perniciousness';

Values assigned to 'module.exports' and local variables

If your module exports symbols that are not directly assigned to module.exports, you can use the @exports tag in place of the @module tag. The @exports tag tells JSDoc that a symbol represents the value exported by a module.

Object literal assigned to a local variable and module.exports

/**

* Color mixer.

* @exports color/mixer

*/

var mixer = module.exports = {

/**

* Blend two colors together.

* @param {string} color1 - The first color, in hexadecimal format.

* @param {string} color2 - The second color, in hexadecimal format.

* @return {string} The blended color.

*/

blend: function(color1, color2) {

// ...

}

};

Properties added to 'this'

When a module adds a property to its this object, JSDoc 3 automatically recognizes that the new property is exported by the module:

Properties added to a module's 'this' object

/**

* Module for bookshelf-related utilities.

* @module bookshelf

*/

/**

* Create a new Book.

* @class

* @param {string} title - The title of the book.

*/

this.Book = function(title) {

/** The title of the book. */

this.title = title;

}

AMD Modules

Overview

JSDoc 3 makes it possible to document modules that use the Asynchronous Module Definition (AMD) API, which is implemented by libraries such as RequireJS. This page explains how to document an AMD module for JSDoc, based on the coding conventions that your module uses.

If you're documenting CommonJS or Node.js modules, see CommonJS Modules for instructions.

Module identifiers

When you document an AMD module, you'll use an @exports tag or @module tag to document the identifier that's passed to the require() function. For example, if users load the module by calling require('my/shirt', /* callback */), you'll write a JSDoc comment that contains the tag @exports my/shirt or @module my/shirt. The examples below can help you decide which of these tags to use.

If you use the @exports or @module tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

When you use a JSDoc namepath to refer to a module from another JSDoc comment, you must add the prefix module:. For example, if you want the documentation for the module my/pants to link to the module my/shirt, you could use the @see tag to document my/pants as follows:

/**

* Pants module.

* @module my/pants

* @see module:my/shirt

*/

Similarly, the namepath for each member of the module will start with module:, followed by the module name. For example, if your my/pants module exports a Jeans constructor, and Jeans has an instance method named hem, the instance method's longname is module:my/pants.Jeans#hem.

Function that returns an object literal

If you define your AMD module as a function that returns an object literal, use the @exports tag to document the module's name. JSDoc will automatically detect that the object's properties are members of the module.

Function that returns an object literal

define('my/shirt', function() {

/**

* A module representing a shirt.

* @exports my/shirt

*/

var shirt = {

/** The module's `color` property. */

color: 'black',

/**

* Create a new Turtleneck.

* @class

* @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).

*/

Turtleneck: function(size) {

/** The class's `size` property. */

this.size = size;

}

};

return shirt;

});

Function that returns another function

If you define your module as a function that exports another function, such as a constructor, you can use a standalone comment with a @module tag to document the module. You can then use an @alias tag to tell JSDoc that the function uses the same longname as the module.

Function that returns a constructor

/**

* A module representing a jacket.

* @module my/jacket

*/

define('my/jacket', function() {

/**

* Create a new jacket.

* @class

* @alias module:my/jacket

*/

var Jacket = function() {

// ...

};

/** Zip up the jacket. */

Jacket.prototype.zip = function() {

// ...

};

return Jacket;

});

Module declared in a return statement

If you declare your module object in a function's return statement, you can use a standalone comment with a @module tag to document the module. You can then add an @alias tag to tell JSDoc that the module object has the same longname as the module.

Module declared in a return statement

/**

* Module representing a shirt.

* @module my/shirt

*/

define('my/shirt', function() {

// Do setup work here.

return /** @alias module:my/shirt */ {

/** Color. */

color: 'black',

/** Size. */

size: 'unisize'

};

});

Module object passed to a function

If the module object is passed into the function that defines your module, you can document the module by adding an @exports tag to the function parameter. This pattern is supported in JSDoc 3.3.0 and later.

Module object passed to a function

define('my/jacket', function(

/**

* Utility functions for jackets.

* @exports my/jacket

*/

module) {

/**

* Zip up a jacket.

* @param {Jacket} jacket - The jacket to zip up.

*/

module.zip = function(jacket) {

// ...

};

});

Multiple modules defined in one file

If you define more than one AMD module in a single JavaScript file, use the @exports tag to document each module object.

Multiple AMD modules defined in one file

// one module

define('html/utils', function() {

/**

* Utility functions to ease working with DOM elements.

* @exports html/utils

*/

var utils = {

/**

* Get the value of a property on an element.

* @param {HTMLElement} element - The element.

* @param {string} propertyName - The name of the property.

* @return {*} The value of the property.

*/

getStyleProperty: function(element, propertyName) { }

};

/**

* Determine if an element is in the document head.

* @param {HTMLElement} element - The element.

* @return {boolean} Set to `true` if the element is in the document head,

* `false` otherwise.

*/

utils.isInHead = function(element) { }

return utils;

}

);

// another module

define('tag', function() {

/** @exports tag */

var tag = {

/**

* Create a new Tag.

* @class

* @param {string} tagName - The name of the tag.

*/

Tag: function(tagName) {

// ...

}

};

return tag;

});

Block Tags

@abstract (synonyms: @virtual)

This member must be implemented (or overridden) by the inheritor.

@access

Specify the access level of this member (private, package-private, public, or protected).

@alias

Treat a member as if it had a different name.

@async

Indicate that a function is asynchronous.

@augments (synonyms: @extends)

Indicate that a symbol inherits from, and adds to, a parent symbol.

@author

Identify the author of an item.

@borrows

This object uses something from another object.

@callback

Document a callback function.

@class (synonyms: @constructor)

This function is intended to be called with the "new" keyword.

@classdesc

Use the following text to describe the entire class.

@constant (synonyms: @const)

Document an object as a constant.

@constructs

This function member will be the constructor for the previous class.

@copyright

Document some copyright information.

@default (synonyms: @defaultvalue)

Document the default value.

@deprecated

Document that this is no longer the preferred way.

@description (synonyms: @desc)

Describe a symbol.

@enum

Document a collection of related properties.

@event

Document an event.

@example

Provide an example of how to use a documented item.

@exports

Identify the member that is exported by a JavaScript module.

@external (synonyms: @host)

Identifies an external class, namespace, or module.

@file (synonyms: @fileoverview, @overview)

Describe a file.

@fires (synonyms: @emits)

Describe the events this method may fire.

@function (synonyms: @func, @method)

Describe a function or method.

@generator

Indicate that a function is a generator function.

@global

Document a global object.

@hideconstructor

Indicate that the constructor should not be displayed.

@ignore

Omit a symbol from the documentation.

@implements

This symbol implements an interface.

@inheritdoc

Indicate that a symbol should inherit its parent's documentation.

@inner

Document an inner object.

@instance

Document an instance member.

@interface

This symbol is an interface that others can implement.

@kind

What kind of symbol is this?

@lends

Document properties on an object literal as if they belonged to a symbol with a given name.

@license

Identify the license that applies to this code.

@listens

List the events that a symbol listens for.

@member (synonyms: @var)

Document a member.

@memberof

This symbol belongs to a parent symbol.

@mixes

This object mixes in all the members from another object.

@mixin

Document a mixin object.

@module

Document a JavaScript module.

@name

Document the name of an object.

@namespace

Document a namespace object.

@override

Indicate that a symbol overrides its parent.

@package

This symbol is meant to be package-private.

@param (synonyms: @arg, @argument)

Document the parameter to a function.

@private

This symbol is meant to be private.

@property (synonyms: @prop)

Document a property of an object.

@protected

This symbol is meant to be protected.

@public

This symbol is meant to be public.

@readonly

This symbol is meant to be read-only.

@requires

This file requires a JavaScript module.

@returns (synonyms: @return)

Document the return value of a function.

@see

Refer to some other documentation for more information.

@since

When was this feature added?

@static

Document a static member.

@summary

A shorter version of the full description.

@this

What does the 'this' keyword refer to here?

@throws (synonyms: @exception)

Describe what errors could be thrown.

@todo

Document tasks to be completed.

@tutorial

Insert a link to an included tutorial file.

@type

Document the type of an object.

@typedef

Document a custom type.

@variation

Distinguish different objects with the same name.

@version

Documents the version number of an item.

@yields (synonyms: @yield)

Document the value yielded by a generator function.