CommonJS 模块

概述

¥Overview

为了帮助你记录 CommonJS 模块，JSDoc 3 了解 CommonJS 规范中使用的许多约定（例如，向 exports 对象添加属性）。此外，JSDoc 还认可 Node.js 模块 的约定，它扩展了 CommonJS 标准（例如，为 module.exports 赋值）。根据你遵循的编码约定，你可能需要提供一些附加标签来帮助 JSDoc 理解你的代码。

¥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.

本页介绍了如何记录使用多种不同编码约定的 CommonJS 和 Node.js 模块。如果你正在记录异步模块定义 (AMD) 模块（也称为 "RequireJS 模块"），请参阅 AMD 模块。

¥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

在大多数情况下，你的 CommonJS 或 Node.js 模块应包含一个独立的 JSDoc 注释，其中包含 @module 标签。@module 标记的值应该是传递给 require() 函数的模块标识符。例如，如果用户通过调用 require('my/shirt') 加载模块，则你的 JSDoc 注释将包含标签 @module my/shirt。

¥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.

如果你使用不带值的 @module 标记，JSDoc 将尝试根据文件路径猜测正确的模块标识符。

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

当你使用 JSDoc namepath 引用另一个 JSDoc 注释中的模块时，你必须添加前缀 module:。例如，如果你希望模块 my/pants 的文档链接到模块 my/shirt，则可以使用 @see 标签 来记录 my/pants，如下所示：

¥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
 */

同样，模块每个成员的名称路径将以 module: 开头，后跟模块名称。例如，如果你的 my/pants 模块导出 Jeans 构造函数，并且 Jeans 有一个名为 hem 的实例方法，则该实例方法的长名称为 module:my/pants.Jeans#hem。

¥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' 对象的属性

¥Properties of the 'exports' object

记录直接分配给 exports 对象属性的符号是最简单的。JSDoc 将自动识别模块导出这些符号。

¥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.

在以下示例中，my/shirt 模块导出方法 button 和 unbutton。JSDoc 会自动检测模块是否导出这些方法。

¥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() {
    // ...
};

分配给局部变量的值

¥Values assigned to local variables

在某些情况下，导出的符号在添加到 exports 对象之前可能会被分配给局部变量。例如，如果你的模块导出 wash 方法，而模块本身经常调用 wash 方法，则你可以按如下方式编写模块：

¥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() {
    // ...
};

在这种情况下，JSDoc 不会自动将 wash 记录为导出方法，因为 JSDoc 注释紧邻局部变量 wash 而不是 exports.wash 之前出现。一种解决方案是添加 @alias 标签 来定义方法的正确长名称。在本例中，该方法是模块 my/shirt 的静态成员，因此正确的长名称是 module:my/shirt.wash：

¥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:

/**

 * 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 导出的：

¥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' 的值

¥Values assigned to 'module.exports'

在 Node.js 模块中，你可以直接为 module.exports 赋值。本节说明如何记录分配给 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' 的对象字面量

¥Object literal assigned to 'module.exports'

如果模块将对象字面量分配给 module.exports。JSDoc 自动识别模块仅导出此值。此外，JSDoc 会自动为每个属性设置正确的长名称：

¥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) {
        // ..
    }
};

如果你在对象字面量之外向 module.exports 添加属性，也可以使用此模式：

¥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' 的功能

¥Function assigned to 'module.exports'

如果你将函数分配给 module.exports，JSDoc 将自动为该函数设置正确的长名称：

¥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) {
    // ...
};

相同的模式适用于构造函数：

¥The same pattern works for constructor functions:

/**

 * Color mixer.

 * @module color/mixer
 */

/** Create a color mixer. */
module.exports = function ColorMixer() {
    // ...
};

分配给 'module.exports' 的字符串、数字或布尔值

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

对于分配给 module.exports 的值类型（字符串、数字和布尔值），你必须在与 @module 标记相同的 JSDoc 注释中使用 @type 标签 来记录导出值的类型：

¥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:

/**

 * Module representing the word of the day.

 * @module wotd

 * @type {string}
 */

module.exports = 'perniciousness';

分配给 'module.exports' 和局部变量的值

¥Values assigned to 'module.exports' and local variables

如果你的模块导出未直接分配给 module.exports 的符号，则可以使用 @exports 标签 代替 @module 标记。@exports 标签告诉 JSDoc 该符号代表模块导出的值。

¥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.

/**

 * 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' 的属性

¥Properties added to 'this'

当模块向其 this 对象添加属性时，JSDoc 3 自动识别新属性是由模块导出的：

¥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;
}

Related links

• @exports
• @module
• 将名称路径与 JSDoc 一起使用