ネストされたオブジェクトのメソッドをJSDocにするにはどうすればよいですか？
JSDoc3を使用してファイルのドキュメントを生成しようとしましたが、いくつかの問題があります。ファイル（Require.jsモジュール）は基本的に次のようになります。
define([], function() {
/*
* @exports mystuff/foo
*/
var foo = {
/**
* @member
*/
bar: {
/**
* @method
*/
baz: function() { /*...*/ }
}
};
return foo;
}
問題は、生成されたドキュメントにbazが表示されないことです。代わりに、barメンバーをリストするfoo/fooモジュールのドキュメントファイルを取得しますが、barにはbazがありません（fooのソースコードへのリンクのみ）。
代わりにbarのディレクティブを@propertyに変更しようとしました。また、bazのディレクティブを@memberまたは@propertyに変更しようとしましたが、いずれも役立ちません。私が何をしようとも、bazは現れたくないようです。
生成されたドキュメントにbazを表示するために使用できるディレクティブ構造を知っている人はいますか？
追伸私はJSDocサイトでこのようなページを読んでみました http://usejsdoc.org/howto-commonjs-modules.html ですが、それはfoo.barではなくfoo.bar.bazのケースのみを説明しています。
@ module または @ namespace と @ memberof の組み合わせを使用できます。
define([], function() {
/**
* A test module foo
* @version 1.0
* @exports mystuff/foo
* @namespace foo
*/
var foo = {
/**
* A method in first level, just for test
* @memberof foo
* @method testFirstLvl
*/
testFirstLvl: function(msg) {},
/**
* Test child object with child namespace
* @memberof foo
* @type {object}
* @namespace foo.bar
*/
bar: {
/**
* A Test Inner method in child namespace
* @memberof foo.bar
* @method baz
*/
baz: function() { /*...*/ }
},
/**
* Test child object without namespace
* @memberof foo
* @type {object}
* @property {method} baz2 A child method as property defination
*/
bar2: {
/**
* A Test Inner method
* @memberof foo.bar2
* @method baz2
*/
baz2: function() { /*...*/ }
},
/**
* Test child object with namespace and property def.
* @memberof foo
* @type {object}
* @namespace foo.bar3
* @property {method} baz3 A child method as property defination
*/
bar3: {
/**
* A Test Inner method in child namespace
* @memberof foo.bar3
* @method baz3
*/
baz3: function() { /*...*/ }
},
/**
* Test child object
* @memberof foo
* @type {object}
* @property {method} baz4 A child method
*/
bar4: {
/**
* The @alias and @memberof! tags force JSDoc to document the
* property as `bar4.baz4` (rather than `baz4`) and to be a member of
* `Data#`. You can link to the property as {@link foo#bar4.baz4}.
* @alias bar4.baz4
* @memberof! foo#
* @method bar4.baz4
*/
baz4: function() { /*...*/ }
}
};
return foo;
});
コメントごとの編集：（モジュールのシングルページソリューション）
その4いプロパティテーブルなしのbar4。すなわち、bar4から@propertyが削除されました。
define([], function() {
/**
* A test module foo
* @version 1.0
* @exports mystuff/foo
* @namespace foo
*/
var foo = {
/**
* A method in first level, just for test
* @memberof foo
* @method testFirstLvl
*/
testFirstLvl: function(msg) {},
/**
* Test child object
* @memberof foo
* @type {object}
*/
bar4: {
/**
* The @alias and @memberof! tags force JSDoc to document the
* property as `bar4.baz4` (rather than `baz4`) and to be a member of
* `Data#`. You can link to the property as {@link foo#bar4.baz4}.
* @alias bar4.baz4
* @memberof! foo#
* @method bar4.baz4
*/
baz4: function() { /*...*/ },
/**
* @memberof! for a memeber
* @alias bar4.test
* @memberof! foo#
* @member bar4.test
*/
test : true
}
};
return foo;
});
参考資料-
*注自分で試したことはありません。結果を共有してみてください。
簡単な方法は次のとおりです。
/**
* @module mystuff/foo
* @version 1.0
*/
define([], function() {
/** @lends module:mystuff/foo */
var foo = {
/**
* A method in first level, just for test
*/
testFirstLvl: function(msg) {},
/**
* @namespace
*/
bar4: {
/**
* This is the description for baz4.
*/
baz4: function() { /*...*/ },
/**
* This is the description for test.
*/
test : true
}
};
return foo;
});
Jsdocはbaz4.baz4およびtest。@ methodおよび@memberを言う必要はありません。
Jsdoc3がクラスと名前空間のドキュメントをsameページにそれらを定義するモジュールとして置く限り、それを行う方法はわかりません。
小さなライブラリ と 大きなアプリケーション をドキュメント化して、jsdoc3を何ヶ月も使用しています。一部の領域では、@ディレクティブを連打して自分の意志で曲げるよりも、jsdoc3の意志に合わせて曲げることを好みます。
JSDoc3 のProngsの回答を少し改善するために、 @instance アノテーションの代わりに @ member 。
ES6のサンプルコードは次のとおりです。
class Test
{
/**
* @param {object} something
*/
constructor(something)
{
this.somethingElse = something;
/**
* This sub-object contains all sub-class functionality.
*
* @type {object}
*/
this.topology = {
/**
* Informative comment here!
*
* @alias topology.toJSON
* @memberof! Test#
* @instance topology.toJSON
*
* @returns {object} JSON object
*/
toJSON()
{
return deepclone(privatesMap.get(this).innerJSON);
},
...
}
}
}
ネストされた関数を直接ドキュメント化することはできません。私はProngsソリューションが好きではなかったので、名前空間のない別の実装を使用しました（JS、notJava！）。
更新：
OPによって与えられた正確なユースケースを反映するように回答を更新しました（JSdocは使用するのがかなり苦痛なので、これは公平です）。仕組みは次のとおりです。
/** @module foobar */
/** @function */
function foobarbaz() {
/*
* You can't document properties inside a function as members, like you
* can for classes. In Javascript, functions are first-class objects. The
* workaround is to make it a @memberof it's closest parent (the module).
* manually linking it to the function using (see: {@link ...}), and giving
* it a @name.
*/
/**
* Foo object (see: {@link module:foobar~foobarbaz})
* @name foo
* @inner
* @private
* @memberof module:foobar
* @property {Object} foo - The foo object
* @property {Object} foo.bar - The bar object
* @property {function} foo.bar.baz - The baz function
*/
var foo = {
/*
* You can follow the same steps that was done for foo, with bar. Or if the
* @property description of foo.bar is enough, leave this alone.
*/
bar: {
/*
* Like the limitation with the foo object, you can only document members
* of @classes. Here I used the same technique as foo, except with baz.
*/
/**
* Baz function (see: {@link module:foobar~foo})
* @function
* @memberof module:foobar
* @returns {string} Some string
*/
baz: function() { /*...*/ }
}
};
return foo;
}
残念ながらJSdocはJavaの移植版であるため、Javaに対しては意味がありますが、JSには当てはまりません。その逆も同様です。たとえば、JS関数ではファーストクラスオブジェクトの場合、それらはオブジェクトまたは関数として扱うことができます。
/** @function */
function hello() {
/** @member {Object} */
var hi = {};
}
しかし、JSdocはそれを関数として認識するため、そうではありません。名前空間を使用する必要があります。@link、またはクラスにする場合：
/** @class */
function Hello() {
/** @member {Object} */
var hi = {};
}
しかし、それでも意味がありません。 JSにクラスが存在しますか？no、ありません。
より良いドキュメントソリューションを見つける必要があると思います。型の表示方法に関するドキュメントの矛盾さえ見ました（例：{object} vs {Object}）。
また、私の手法を使用して closures を文書化することもできます。