JsDoc Toolkitを使う!
ネームパス
最終更新:
aias-jsdoctoolkit
トップページ > ドックコメントの書き方 >
ネームパス
- このページは公式サイトのhttp://code.google.com/p/jsdoc-toolkit/wiki/NamePathsを日本語に翻訳、一部を再構成したものです。
概要
JsDoc Toolkitが作成するドキュメントにおいて、ドキュメント内のほかの場所にあるJavaScriptの値(関数、クラス、メソッドなど)への参照を記述したいケースは多くあります。そしてその場合に必要となるのは、その値へのパスを示すユニークな識別子です。ネームパス(NamePaths)はまさにそのような識別の手段を提供するもので、インスタンスメンバ、スタティック(静的)メンバ、内部変数も明確に区別できるようになっています。
例
以下に示すクラスには、"say"という名前のインスタンスメソッド、同じく"say"という名前の内部関数、さらにスタティックメソッドにも"say"が定義されています。それらは3つの別々なメソッドで、言語仕様上、互いに独立して存在することが許されています。
Person = function() {
this.say = function() {
return "私はインスタンスメソッドです";
}
function say() {
return "私は内部関数です";
}
}
Person.say = function() {
return "私はスタティックメソッドです";
}
var p = new Person();
p.say(); // -> 私はインスタンスメソッドです
Person.say(); // -> 私はスタティックメソッドです
// 内部関数にアクセスする手段はありません
ネームパスでは、これらのメソッドを以下のように異なる区切り文字を用いて区別します。
インスタンスメソッド | Person#say |
スタティックメソッド | Person.say |
内部関数 | Person-say |
内部関数は Person クラスの外部からアクセス不能であるにもかかわらず、それを参照するための構文が存在するのを奇妙に思うかもしれません。実際"-"はめったに使われることは無いのですが、例えばこの内部関数への参照を返すようなメソッドが存在するようなケースでは、コード内の他の要素が内部関数を参照している可能性があるのです。
下のようにあるコンストラクタのインスタンスメンバがやはりコンストラクタだった場合、ネームパスは単純に各階層の名前をつないで表現します。
/** @constructor */
Person = function() {
/** @constructor */
this.Idea = function() {
this.consider = function(){
return "hmmm";
}
}
}
var p = new Person();
var i = new p.Idea();
i.consider();
このケースでは、 consider メソッドへのネームパスは以下のようになります。
Person#Idea#consider
各階層をつなぐのに、 #.- を自由に組み合わせて使用することができます。
/** @constructor */