我有2种类型的模块：
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时可能与jsdoc吗？
Answer 1:
这是我的第一个SO回答，请让我知道我可以提高未来的答案。
你的具体例子
我一直在寻找这个答案有一个良好的两天，似乎没有要在没有一定的冗余度（如重复函数名）自动记录RequireJS AMD模块的方式。 Karthrik的回答确实生成文档的一个很好的工作，但如果事情的代码被改名的文件仍然会从什么在jsDoc标签生成。
我落得这样做是下面的，这是从KARTHIK的调整。例如。 注意@lends第1行的标签，并去除的@name从jsDoc注释块标记。
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引用
- jsdoc的工具包标记参考 -在jsdoc的工具箱标签大参考。 有一堆的例子呢！
- 2ality的jsDoc介绍 -基于jsDoc的工具包全面的教程。
- jsDoc3参考 -还算完整，但有一些例子。
Answer 2:
jsDoc似乎并不喜欢“定义”和“规定”的电话。
所以，我们结束了使用多个标签，使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;
});
注：记录JS代码的上述方法制定出适合我们同时使用jsDoc。 没有得到一个机会去尝试jsDoc3。
Answer 3:
以该链接从MUXA的回答中，我们看到的文档，也专指RequireJS：
该RequireJS库提供了一个定义方法，可以让你写一个函数返回一个模块对象。 使用@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已建议和其他标签/技术。 相反，我会尽量坚持使用@module ， @exports和@alias在使用的标记文件引用RequireJS 。
我不知道你应该怎么记录您requirejs“主”文件。 如果我理解正确的话，你实际上并没有定义任何模块出现，而是执行取决于几个模块一次性的功能。
Answer 4:
我的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() {
}
});
Answer 5:
看起来事情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由该文件定义和导出。
文章来源: How to document a Require.js (AMD) Modul with jsdoc 3 or jsdoc?
