commonjs转换原生HTML,CommonJS Modules

CommonJS Modules

Overview(概述)

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

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

Module identifiers(模块标识符)

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

Properties of the 'exports' object('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() {

// ...

};

Values assigned to local variables (值分配给局部变量)

在一些情况下，导出的标识符在它被加入到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() {

// ...

};

Values assigned to 'module.exports' (值分配给'module.exports')

在Node.js的模块中，您可以直接给module.exports赋值。本节介绍如何记录分配给module.exports的不同类型的值。

Object literal assigned to 'module.exports'(对象字面量分配给'module.exports')

如果一个模块将一个对象字面量分配给module.exports。JSDoc自动识别这个模块的exports只有这个值。此外，JSDoc自动为每个属性设置正确的longname(长名称)：

例如：对象字面量分配给'module.exports'：/**

* Color mixer.

* @module color/mixer

*/

module.exports = {

/** Blend two colors together. */

blend: function(color1, color2) {

// ...

},

/** Darken a color by the given percentage. */

darken: function(color, percent) {

// ..

}

};

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

例如，通过属性定义，分配给module.exports：/**

* Color mixer.

* @module color/mixer

*/

module.exports = {

/** Blend two colors together. */

blend: function(color1, color2) {

// ...

}

};

/** Darken a color by the given percentage. */

module.exports.darken = function(color, percent) {

// ..

};

Function assigned to 'module.exports'(函数分配给'module.exports')

如果你分配一个函数给module.exports，JSDoc将自动这个函数设置正确的longname(长名称)。

例如，函数分配给'module.exports'：/**

* Color mixer.

* @module color/mixer

*/

/** Blend two colors together. */

module.exports = function(color1, color2) {

// ...

};

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

例如，构造函数分配给'module.exports'：/**

* Color mixer.

* @module color/mixer

*/

/** Create a color mixer. */

module.exports = function ColorMixer() {

// ...

};

String, number, or boolean assigned to 'module.exports'(字符串，数字，或布尔值分配给'module.exports')

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

例如，字符串分配给'module.exports'/**

* Module representing the word of the day.

* @module wotd

* @type {string}

*/module.exports = 'perniciousness';

Values assigned to 'module.exports' and local variables (值分配给'module.exports'和局部变量)

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

例如，对象字面量分配给一个局部变量和module.exports：/**

* Color mixer.

* @exports color/mixer

*/

var mixer = module.exports = {

/** Blend two colors together. */

blend: function(color1, color2) {

// ...

}

};

Properties added to 'this'(属性添加到'this')

当一个模块添加属性到它的this对象，JSDoc3自动识别新的属性会被该模块导出。

例如，属性添加到一个模块的'this'对象：/** @module bookshelf */

/** @class */

this.Book = function(title) {

/** The title of the book. */

this.title = title;

}