[英]How to document a Require.js (AMD) Modul with jsdoc 3 or jsdoc?
我有两种类型的模块:
Require.js主文件 :
require.config({
baseUrl: "/another/path",
paths: {
"some": "some/v1.0"
},
waitSeconds: 15,
locale: "fr-fr"
});
require( ["some/module", "my/module", "a.js", "b.js"],
function(someModule, myModule) {
}
);
调解员模式:
define([], function(Mediator){
var channels = {};
if (!Mediator) Mediator = {};
Mediator.subscribe = function (channel, subscription) {
if (!channels[channel]) channels[channel] = [];
channels[channel].push(subscription);
};
Mediator.publish = function (channel) {
if (!channels[channel]) return;
var args = [].slice.call(arguments, 1);
for (var i = 0, l = channels[channel].length; i < l; i++) {
channels[channel][i].apply(this, args);
}
};
return Mediator;
});
如果可能的话,我怎么能用jsdoc3记录这个?
这是我在SO上的第一个答案,请让我知道如何改进未来的答案。
我一直在寻找一个好的两天的答案,并且似乎没有办法自动记录RequireJS AMD模块而没有一些冗余(如重复的函数名称)。 Karthrik的答案很好地生成了文档,但是如果在代码中重命名了某些内容,那么仍然会从jsDoc标记中的内容生成文档。
我最终做的是以下内容,这是根据Karthik的例子进行调整的。 注意第1行的@lends
标记,以及从jsDoc注释块中删除@name
标记。
define([], /** @lends Mediator */ function(Mediator){
/**
* Mediator class
* This is the interface class for user related modules
* @class Mediator
*/
var channels = {};
if (!Mediator) Mediator = {};
/**
* .... description goes here ...
* @function
*
* @param {Number} channel .....
* @param {String} subscription ..............
* @example
* add the sample code here if relevent.
*
*/
Mediator.subscribe = function (channel, subscription) {
if (!channels[channel]) channels[channel] = [];
channels[channel].push(subscription);
};
Mediator.publish = function (channel) {
if (!channels[channel]) return;
var args = [].slice.call(arguments, 1);
for (var i = 0, l = channels[channel].length; i < l; i++) {
channels[channel][i].apply(this, args);
}
};
return Mediator;
});
根据我的理解, @lends
标记将解释来自下一个对象文字的所有jsDoc注释,作为@lends
标记引用的类的一部分。 在这种情况下,下一个对象文字是以function(Mediator) {
开头的文字。 删除@name
标记,以便jsDoc在源代码中查找函数名称等。
注意:我在@exports
标记的同一位置使用了@lends
标记。 虽然这有效,但它会在文档中创建一个模块......我只想为该类生成文档。 这种方式适合我!
jsDoc似乎不喜欢“define”和“require”调用。
因此,我们最终使用多个标记来使jsDoc工具获取构造函数和其他特定的类方法。 请看下面的示例:我刚从源代码中复制粘贴,并将其替换为您的类名和方法名。 希望对你有效。
define([], function(Mediator){
/**
* Mediator class
* This is the interface class for user related modules
* @name Mediator
* @class Mediator
* @constructor
* @return Session Object
*/
var channels = {};
if (!Mediator) Mediator = {};
/**
* .... description goes here ...
* @name Mediator#subscribe
* @function
*
* @param {Number} channel .....
* @param {String} subscription ..............
* @example
* add the sample code here if relevent.
*
*/
Mediator.subscribe = function (channel, subscription) {
if (!channels[channel]) channels[channel] = [];
channels[channel].push(subscription);
};
Mediator.publish = function (channel) {
if (!channels[channel]) return;
var args = [].slice.call(arguments, 1);
for (var i = 0, l = channels[channel].length; i < l; i++) {
channels[channel][i].apply(this, args);
}
};
return Mediator;
});
注意:使用jsDoc时,上面记录JS代码的方法对我们来说效果很好。 没有机会尝试jsDoc3。
从Muxa的答案中获取链接 ,我们看到文档特别提到RequireJS:
RequireJS库提供了一个define方法,允许您编写函数以返回模块对象。 使用@exports标记来记录对象文字的所有成员都应记录为模块的成员。
define('my/shirt', function () {
/**
* A module representing a shirt.
* @exports my/shirt
* @version 1.0
*/
var shirt = {
/** A property of the module. */
color: "black",
/** @constructor */
Turtleneck: function(size) {
/** A property of the class. */
this.size = size;
}
};
return shirt;
});
所以在上面的例子中,我们看到jsdoc将解析my/shirt
模块并将其记录为具有两个成员:属性color
,以及类Turtleneck
。 Turtleneck
类也将被记录为具有自己的属性size
。
使用@alias标记简化了RequireJS中构造函数模块的记录。
/**
* A module representing a jacket.
* @module jacket
*/
define('jacket', function () {
/**
* @constructor
* @alias module:jacket
*/
var exports = function() {
}
/** Open and close your Jacket. */
exports.prototype.zip = function() {
}
return exports;
});
如果要将构造函数导出为将用作实例化对象的类的模块,则上面是您要使用的内容。 总而言之,我不确定是否使用了@lends
和其他标签/技术。 相反,我会尝试坚持引用RequireJS的文档中使用的@module
, @exports
和@alias
标记。
我不确定你应该如何记录你的requirejs'main'文件。 如果我理解正确,你实际上并没有在那里定义任何模块,而是执行依赖于几个模块的一次性函数。
我的AMD类使用稍微不同的形式,但JSDoc也没有记录它们,所以我想我会分享对我有用的东西。
全局命名空间中的构造函数会自动添加:
/**
* @classdesc This class will be documented automatically because it is not in
* another function.
* @constructor
*/
function TestClassGlobal() {
/**
* This is a public method and will be documented automatically.
*/
this.publicMethod = function() {
};
}
如果要在AMD模块内的构造函数上使用此行为,请将其声明为全局或命名空间的成员 :
define([], function() {
/**
* @classdesc This won't be automatically documented unless you add memberof,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}
/**
* @classdesc This won't be automatically documented unless you add global,
* because it's inside another function.
* @constructor
* @global
*/
function TestClassForcedGlobal() {
}
});
看起来JSDoc3中的事情变得更加简单了。 以下对我有用:
/**
* Mediator Module
* @module Package/Mediator
*/
define([], function(Mediator){
var channels = {};
if (!Mediator) Mediator = {};
/**
* Subscribe
* @param {String} channel Channel to listen to
* @param {Function} subscription Callback when channel updates
* @memberOf module:Package/Mediator
*/
Mediator.subscribe = function (channel, subscription) {
if (!channels[channel]) channels[channel] = [];
channels[channel].push(subscription);
};
/**
* Publish
* @param {String} channel Channel that has new content
* @memberOf module:Package/Mediator
*/
Mediator.publish = function (channel) {
if (!channels[channel]) return;
var args = [].slice.call(arguments, 1);
for (var i = 0, l = channels[channel].length; i < l; i++) {
channels[channel][i].apply(this, args);
}
};
return Mediator;
});
但是,我可能会对代码进行以下更改:
/**
* Mediator Module
* @module Package/Mediator
*/
define([], function(){
var channels = {};
var Mediator = {}
...
原因是,模块说它定义了Mediator
,但似乎是从Mediator
其他一些实例借用的。 我不确定我明白这一点。 在这个版本中,很明显Mediator
是由这个文件定义并导出的。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.