Table of Contents
- Module identifiers
- Properties of the 'exports' object
- Values assigned to local variables
- Values assigned to 'module.exports'
- Values assigned to 'module.exports' and local variables
- Properties added to 'this'
- Related Links
To help you document CommonJS modules, JSDoc 3 understands many of the
conventions used in the CommonJS specification (for example, adding properties to the
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
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.
In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that
@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
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
link to the module
my/shirt, you could use the
@see tag to document
/** * 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
an instance method named
hem, the instance method's longname is
Properties of the 'exports' object
It's easiest to document symbols that are directly assigned to a property of the
JSDoc will automatically recognize that the module exports these symbols.
In the following example, the
my/shirt module exports the methods
will automatically detect that the module exports these methods.
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
wash method, you might write the module as follows:
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
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
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
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
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
You can also use this pattern if you add properties to
module.exports outside of the object
Function assigned to 'module.exports'
If you assign a function to
module.exports, JSDoc will automatically set the correct longname for
The same pattern works for constructor functions:
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
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.
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: