JSDoc でネームパスを使用する
JSDoc でのネームパス
文書の他の場所にある JavaScript 変数を参照する場合は、その変数にマップする一意の識別子を提供する必要があります。ネームパスを使用することでそのようにして、インスタンス メンバー、静的メンバー、および内部変数を区別できます。
myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash
次の例では、「say」という名前のインスタンスメソッド、同じく「say」という名前の内部関数、「say」という名前の静的メソッドを示します。これらは互いに独立して存在する 3 つの異なるメソッドです。
/** @constructor */
Person = function() {
this.say = function() {
return "I'm an instance.";
}
function say() {
return "I'm inner.";
}
}
Person.say = function() {
return "I'm static.";
}
var p = new Person();
p.say(); // I'm an instance.
Person.say(); // I'm static.
// there is no way to directly access the inner function from here
3 つの異なるメソッドを参照するには、3 つの異なるネームパス構文を使用します。
Person#say // the instance method named "say."
Person.say // the static method named "say."
Person~say // the inner method named "say."
そのメソッドが定義されている関数から直接アクセスできない場合に、内部メソッドを参照する構文が存在するのは不思議に思えるかもしれません。これは事実であり、そのため「~」構文はほとんど使用されませんが、他のメソッドからそのコンテナー内の内部メソッドへの参照を返すことは可能なので、コード内の他の場所にあるオブジェクトが内部メソッドを借りることもできます。
コンストラクターにコンストラクターであるインスタンス メンバーがある場合、ネームパスを連結して長いネームパスを作成するだけで良いことに注意してください。
/** @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
この連結は、連結記号 # . ~ の任意の組み合わせで使用できます。
/** A module. Its name is module:foo/bar.
* @module foo/bar
*/
/** The built in string object. Its name is external:String.
* @external String
*/
/** An event. Its name is module:foo/bar.event:MyEvent.
* @event module:foo/bar.event:MyEvent
*/
ネームパスにはいくつかの特殊なケースがあります。 @module 名前に「module:」という接頭辞が付けられ、@external 名前に「external:」という接頭辞が付けられ、@event 名前に「event:」という接頭辞が付けられます。
/** @namespace */
var chat = {
/**
* Refer to this by {@link chat."#channel"}.
* @namespace
*/
"#channel": {
/**
* Refer to this by {@link chat."#channel".open}.
* @type {boolean}
* @defaultvalue
*/
open: true,
/**
* Internal quotes have to be escaped by backslash. This is
* {@link chat."#channel"."say-\"hello\""}.
*/
'say-"hello"': function (msg) {}
}
};
/**
* Now we define an event in our {@link chat."#channel"} namespace.
* @event chat."#channel"."op:announce-motd"
*/
上に、メンバー名に「変わった」文字が含まれる名前空間の例を示します (ハッシュ文字、ダッシュ、さらに引用符)。これらを参照するには、名前を引用符で囲むだけで済みます: chat."#channel", chat."#channel"."op:announce-motd" など。名前内の引用符には、バックスラッシュでエスケープする必要があります: chat."#channel"."say-"hello"".