CommonJS 模块¶
概述¶
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. 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 在JSDoc 3中使用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 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.
‘exports’ 对象的属性¶
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.
/**
* Shirt module.
* @module my/shirt
*/
/** Button the shirt. */
exports.button = function() {
// ...
};
/** Unbutton the shirt. */
exports.unbutton = function() {
// ...
};
## 分配给局部变量的值
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:
/**
* 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 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:
/**
* 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:
/**
* Shirt module.
* @module my/shirt
*/
var wash =
/** Wash the shirt. */
exports.wash = function() {
// ...
};
分配给 ‘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.
分配给 ‘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:
/**
* 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:
/**
* 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) {
// ..
};
分配给 ‘module.exports’ 的函数¶
If you assign a function to module.exports, JSDoc will automatically
set the correct longname for the function:
/**
* 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) {
// ...
};
相同的模式适用于构造函数:
/**
* Color mixer.
* @module color/mixer
*/
/** Create a color mixer. */
module.exports = function ColorMixer() {
// ...
};
分配给 ‘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 in the same JSDoc comment as the @module tag:
/**
* Module representing the word of the day.
* @module wotd
* @type {string}
*/
module.exports = 'perniciousness';
分配给 ‘module.exports’ 和局部变量的值¶
If your module exports symbols that are not directly assigned to module.exports,
you can use the @exports in place of the @module tag.
The @exports tag tells JSDoc that a symbol represents the value exported by a module.
/**
* 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) {
// ...
}
};
添加到 ‘this’ 的属性¶
When a module adds a property to its this object,
JSDoc 3 automatically recognizes that the new property is exported by the module:
/**
* 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;
}