CommonJS 模块
概述
为了帮助您记录CommonJS 模块，JSDoc 3 理解 CommonJS 规范中使用的许多约定（例如，向 exports 对象添加属性）。此外，JSDoc 识别Node.js 模块的约定，这些约定扩展了 CommonJS 标准（例如，将值分配给 module.exports）。根据您遵循的编码约定，您可能需要提供一些其他标签来帮助 JSDoc 理解您的代码。
此页面解释了如何记录使用多种不同编码约定的 CommonJS 和 Node.js 模块。如果您正在记录异步模块定义 (AMD) 模块（也称为“RequireJS 模块”），请参阅AMD 模块。
模块标识符
在大多数情况下，您的 CommonJS 或 Node.js 模块应包含一个独立的 JSDoc 注释，其中包含@module 标签。@module 标签的值应传递给 require() 函数的模块标识符。例如，如果用户通过调用 require('my/shirt') 加载模块，您的 JSDoc 注释将包含标签 @module my/shirt。
如果您在没有值的情况下使用 @module 标签，JSDoc 将尝试根据文件路径猜测正确的模块标识符。
当您使用 JSDoc 名称路径从另一个 JSDoc 注释引用模块时，您必须添加前缀 module:。例如，如果您希望模块 my/pants 的文档链接到模块 my/shirt，您可以使用@see 标签将 my/pants 记录如下
/**
* Pants module.
* @module my/pants
* @see module:my/shirt
*/
类似地，模块的每个成员的名称路径将以 module: 开头，后跟模块名称。例如，如果您的 my/pants 模块导出 Jeans 构造函数，并且 Jeans 有一个名为 hem 的实例方法，则实例方法的长名称是 module:my/pants.Jeans#hem。
'exports' 对象的属性
最容易记录直接分配给 exports 对象的属性的符号。JSDoc 将自动识别模块导出这些符号。
在以下示例中，my/shirt 模块导出方法 button 和 unbutton。JSDoc 将自动检测模块导出这些方法。
/**
* Shirt module.
* @module my/shirt
*/
/** Button the shirt. */
exports.button = function() {
// ...
};
/** Unbutton the shirt. */
exports.unbutton = function() {
// ...
};
分配给局部变量的值
在某些情况下，导出的符号可能会在添加到 exports 对象之前分配给局部变量。例如，如果您的模块导出 wash 方法，并且模块本身经常调用 wash 方法，您可以按如下方式编写模块
/**
* Shirt module.
* @module my/shirt
*/
/** Wash the shirt. */
var wash = exports.wash = function() {
// ...
};
在这种情况下，JSDoc 不会 自动将 wash 记录为导出的方法，因为 JSDoc 注释出现在局部变量 wash 而不是 exports.wash 之前。一种解决方案是添加@alias 标签，该标签为方法定义正确的长名称。在这种情况下，该方法是模块 my/shirt 的静态成员，因此正确的长名称是 module:my/shirt.wash
/**
* Shirt module.
* @module my/shirt
*/
/**
* Wash the shirt.
* @alias module:my/shirt.wash
*/
var wash = exports.wash = function() {
// ...
};
另一种解决方案是移动方法的 JSDoc 注释，使其紧接在 exports.wash 之前。此更改允许 JSDoc 检测 wash 由模块 my/shirt 导出
/**
* Shirt module.
* @module my/shirt
*/
var wash =
/** Wash the shirt. */
exports.wash = function() {
// ...
};
分配给 'module.exports' 的值
在 Node.js 模块中，你可以直接为 module.exports 分配一个值。本节说明如何记录分配给 module.exports 的不同类型的值。
分配给“module.exports”的对象字面量
如果模块将对象字面量分配给 module.exports。JSDoc 会自动识别该模块仅导出此值。此外，JSDoc 会自动为每个属性设置正确的 longname
/**
* 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) {
// ..
}
};
如果你在对象字面量之外向 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.
*/
module.exports.darken = function(color, percent) {
// ..
};
分配给“module.exports”的函数
如果你将函数分配给 module.exports，JSDoc 会自动为该函数设置正确的 longname
/**
* 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”的字符串、数字或布尔值
对于分配给 module.exports 的值类型（字符串、数字和布尔值），你必须使用与 @module 标记相同的 JSDoc 注释中的 @type 标记 来记录导出的值的类型
/**
* Module representing the word of the day.
* @module wotd
* @type {string}
*/
module.exports = 'perniciousness';
分配给“module.exports”的值和局部变量
如果你的模块导出了未直接分配给 module.exports 的符号，你可以使用 @exports 标记 来代替 @module 标记。@exports 标记告诉 JSDoc 一个符号表示模块导出的值。
/**
* 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”的属性
当模块向其 this 对象添加属性时，JSDoc 3 会自动识别该新属性是由该模块导出的
/**
* 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;
}