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
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.
In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that contains a
@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
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
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
unbutton. JSDoc 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 calls the
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
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
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 property:
You can also use this pattern if you add properties to
module.exports outside of the object literal:
Function assigned to 'module.exports'
If you assign a function to
module.exports, JSDoc will automatically set the correct longname for the function:
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:
Using namepaths with JSDoc 3