JSDoc中文文档(@use JSDoc)

添加CommonJS 模块

目录

概述

为了帮助您记录CommonJS modules,JSDoc3能理解很多在CommonJS的规范中使用的约定(例如,添加属性到exports对象)。此外,JSDoc承认的Node.js modules的约定,它扩展了CommonJS的标准(例如,将值分配给module.exports)。根据您所遵循编码约定,您可能需要提供一些额外的标签,以帮助JSDoc理解你的代码。

本页面说明如何记录使用几种不同编码约定的CommonJS和Node.js的模块。如果你要记录异步模块定义(AMD)模块(比如大家熟知的"RequireJS模块"),请查看AMD Modules

模块标识符

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

如果你使用不带值的@module 标签,JSDoc会基于文件路径尝试猜测正确的模块标识符。

当您使用 JSDoc namepath(名称路径)从另一个JSDoc注释中引用一个模块,您必须添加前缀module:。例如,如果你想模块my/pants的文档 连接到模块my/shirt,您可以使用@see 标签来描述my/pants,如下:

/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

同样,模块中每个成员的namepath (名称路径)将以module: 开始,后面跟模块名字。例如,如果你的my/pants模块输出一个Jeans构造函数,并且Jeans 有一个名为hem的实例方法,那么这个实例方法longname(长名称)是module:my/pants.Jeans#hem

'exports'对象的属性

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

在下面的例子中,my/shirt 模块导出buttonunbutton 方法。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 标签,用来正确定义方法的longname(长名称)。在这种情况下,该方法是模块 my/shirt 的静态成员,所以正确的长名字是module:my/shirt.wash

示例: longname(长名称)定义在 @alias 标签中
/**
 * 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导出的:

示例: JSDoc注释放在exports.wash之前
/**
 * 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自动识别这个模块的exports只有这个值。此外,JSDoc自动为每个属性设置正确的longname(长名称):

示例: 对象字面量赋值给'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.
     */
    darken: function(color, percent) {
        // ..
    }
};

您也可以使用另一种模式,在module.exports对象字面量以外添加属性:

示例: 通过属性定义,赋值给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(长名称)。

示例: 函数赋值给 'module.exports'
/**
 * 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) {
    // ...
};

同样的模式适用于构造函数:

示例: 构造函数赋值给 'module.exports'
/**
 * Color mixer.
 * @module color/mixer
 */

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

字符串,数字,或布尔值赋值给 'module.exports'

对于赋值给module.exports值类型(字符串,数字和布尔值),你必须在和@module标签同一JSDoc注释块中通过使用 @type 标签记录导出的值类型。

示例: 字符串赋值给 module.exports
/**
 * Module representing the word of the day.
 * @module wotd
 * @type {string}
 */

module.exports = 'perniciousness';

V赋值给 'module.exports' 和局部变量

如果你的模块导出标识符不直接分配给module.exports,您可以使用@exports标签代替@module标签。@exports 标签告诉JSDoc,这个标识符表示是模块导出的值。

示例: 对象字面量赋值给局部变量和 module.exports
/**
 * 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对象,JSDoc3自动识别新的属性会被该模块导出。

示例: 属性添加到一个模块的'this'对象
/**
 * 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;
}