モジュールには 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 で文書化するにはどうすればよいでしょうか?
ベストアンサー1
これは SO での私の最初の回答です。今後の回答をどのように改善できるか教えてください。
具体的な例
私はこれに対する答えを 2 日間探していましたが、RequireJS AMD モジュールを冗長性 (関数名の繰り返しなど) なしで自動的にドキュメント化する方法がないようです。Karthrik の回答はドキュメントの生成をうまく行っていますが、コード内で何かの名前が変更された場合でも、ドキュメントは jsDoc タグの内容から生成されます。
私が最終的に行ったことは、Karthik の例を調整した次のとおりです。1@lends行目のタグと、@namejsDoc コメント ブロックからタグが削除されていることに注意してください。
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 ツールキットに基づいた包括的なチュートリアル。
- jsDoc3 リファレンス- かなり不完全ですが、いくつか例があります。