AMD Modules
Overview(概述)
JSDoc3 可以使用异步模块定义(AMD)API记录模块,这是由库实现的,如RequireJS。本页面说明根据您的模块使用的编码约定,如何使用JSDoc记录AMD模块。
如果你记录CommonJS或 Node.js的模块,见CommonJS 模块的说明。
Module identifiers(模块标识符)
当您记录一个AMD模块时,你要使用 @exports
标签或@module
标签 来记录真实传递给require()
函数的标识符。例如,如果用户通过调用require('my/shirt', /* callback */)
来加载该模块,你会写一个包含@exports my/shirt
或 @module my/shirt
标签的JSDoc注释。下面的例子可以帮助你决定使用哪些标签。
如果你使用不带值的@exports
或 @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
。
Function that returns an object literal(函数返回一个对象字面量)
如果你定义AMD模块作为一个函数,该函数返回一个对象字面量, 使用@exports
标签来记录模块的名称。JSDoc会自动检测该对象的属性是模块的成员。
例如,函数返回一个对象字面量:
define('my/shirt', function() {
/**
* A module representing a shirt.
* @exports my/shirt
*/
var shirt = {
/** The module's `color` property. */
color: 'black',
/** @constructor */
Turtleneck: function(size) {
/** The class' `size` property. */
this.size = size;
}
};
return shirt;
});
Function that returns another function(函数返回另一个函数)
如果你定义模块作为一个函数,导出的另一个函数,比如构造函数,你可以使用一个独立的带有@module
标签的注释来记录模块。然后,您可以使用一个@alias
标签告诉JSDoc该函数使用相同的longname(长名称)作为模块。
例如,函数返回另一个函数:
/**
* A module representing a jacket.
* @module my/jacket
*/
define('my/jacket', function() {
/**
* @constructor
* @alias module:my/jacket
*/
var Jacket = function() {
// ...
};
/** Zip up the jacket. */
Jacket.prototype.zip = function() {
// ...
};
return Jacket;
});
Module declared in a return statement (模块声明在return语句中)
如果你在一个函数的return
语句中声明你的模块对象,你可以使用一个独立的带有@module
标签的注释来记录模块。然后,您可以使用一个@alias
标签告诉JSDoc该函数使用相同的longname(长名称)作为模块。
例如,模块声明在return语句中:
/**
* Module representing a shirt.
* @module my/shirt
*/
define('my/shirt', function() {
// Do setup work here.
return /** @alias module:my/shirt */ {
/** Color. */
color: 'black',
/** Size. */
size: 'unisize'
};
});
Module object passed to a function(模块对象传递给一个函数)
如果模块对象传递到定义你的模块的函数,你可以通过给函数参数添加@exports
标签来记录模块。这种模式在JSDoc3.3.0及更高版本中支持。
例如,模块对象传递给一个函数:
define('my/jacket', function(
/**
* Utility functions for jackets.
* @exports my/jacket
*/
module) {
/**
* Zip up a jacket.
* @param {Jacket} jacket - The jacket to zip up.
*/
module.zip = function(jacket) {
// ...
};
});
Multiple modules defined in one file(多模块定义在一个文件中)
如果你在一个单一的JavaScript文件中定义多个AMD模块,你应该使用@exports
标签来记录每个模块对象。
例如,多模块定义在一个文件中:
// one module
define('html/utils', function() {
/**
* Utility functions to ease working with DOM elements.
* @exports html/utils
*/
var utils = {
/** Get the value of a property on an element. */
getStyleProperty: function(element, propertyName) { }
};
/** Determine if an element is in the document head. */
utils.isInHead = function(element) { }
return utils;
}
);
// another module
define('tag', function() {
/** @exports tag */
var tag = {
/** @class */
Tag: function(tagName) {
// ...
}
};
return tag;
});