jsdoc 3またはjsdocを使用してRequire.js（AMD）モジュールを文書化する方法は？
私は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;
});
Jsdocでも可能であれば、jsdoc3でこれを文書化するにはどうすればよいですか？
これはSOに関する私の最初の回答です。今後の回答を改善する方法を教えてください。
あなたの具体例
私はこれに対する答えを2日間探していましたが、冗長性（関数名の繰り返しなど）なしでRequireJSAMDモジュールを自動的に文書化する方法はないようです。 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リファレンス
- jsdoc-toolkitタグリファレンス -jsdoc-toolkitのタグの優れたリファレンス。例もたくさんあります！
- 2alityのjsDocイントロ -jsDoc-toolkitに基づく包括的なチュートリアル。
- jsDoc3リファレンス -かなり不完全ですが、いくつかの例があります。
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;
});
注：JSコードを文書化する上記の方法は、jsDocを使用しているときにうまく機能しました。 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と2つのメンバーを持つものとして文書化することがわかります。クラス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の「メイン」ファイルをどのように文書化する必要があるのかわかりません。私が正しく理解していれば、実際にはそこでモジュールを定義しているのではなく、複数のモジュールに依存する1回限りの関数を実行しています。
私の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がこのファイルによって定義され、エクスポートされていることは明らかです。