構文
@lends <namepath>
概要
@lends タグを使用すると、オブジェクトのリテラルのすべてのメンバを、指定された名前を持つシンボルのメンバであるかのように記述できます。メンバから名前付きクラスを作成する関数にオブジェクトのリテラルを渡す場合、この使用方法が便利です。
例
この例では、ヘルパー関数を用いて Person という名前のクラスを作成し、インスタンスメソッドである initialize と say に名前を付けます。これは、ほとんどのフレームワークがクラスの作成を処理する方法に似ています。
// We want to document this as being a class
var Person = makeClass(
// We want to document these as being methods
{
initialize: function(name) {
this.name = name;
},
say: function(message) {
return this.name + " says: " + message;
}
}
);
コメントがなければ、JSDoc はこのコードが、2 つのメソッドを持つ Person クラスを作成することは認識できません。メソッドを記述するには、オブジェクトのリテラルの直前にあるドキュメントコメントに @lends タグを使用する必要があります。@lends タグは、そのオブジェクトのリテラルのすべてのメンバ名が、Person という名前の変数に「貸し出されている」ことを JSDoc に伝えます。また、各メソッドにコメントを追加する必要があります。
次の例では、欲しいものに近いものになります
/** @class */
var Person = makeClass(
/** @lends Person */
{
/**
* Create a `Person` instance.
* @param {string} name - The person's name.
*/
initialize: function(name) {
this.name = name;
},
/**
* Say something.
* @param {string} message - The message to say.
* @returns {string} The complete message.
*/
say: function(message) {
return this.name + " says: " + message;
}
}
);
initialize と say という名前の関数が記述されますが、それらは Person クラスのスタティックメソッドとして表示されます。おそらく、それが目的だったのですが、ここでは initialize と say が Person クラスのインスタンスに属するようにします。そのため、メソッドをクラスのプロトタイプに貸し出すことで、少し変更します。
/** @class */
var Person = makeClass(
/** @lends Person.prototype */
{
/**
* Create a `Person` instance.
* @param {string} name - The person's name.
*/
initialize: function(name) {
this.name = name;
},
/**
* Say something.
* @param {string} message - The message to say.
* @returns {string} The complete message.
*/
say: function(message) {
return this.name + " says: " + message;
}
}
);
最後のステップ: クラスフレームワークは、貸し出された initialize 関数を使用して Person のインスタンスを作成しますが、Person インスタンスは、それ自身の initialize メソッドを持ちません。その対処法は、貸し出された関数の @constructs タグを追加することです。また、@class タグも削除することを忘れないでください。そうしないと、2 つのクラスが記述されてしまいます。
var Person = makeClass(
/** @lends Person.prototype */
{
/**
* Create a `Person` instance.
* @constructs
* @param {string} name - The person's name.
*/
initialize: function(name) {
this.name = name;
},
/**
* Say something.
* @param {string} message - The message to say.
* @returns {string} The complete message.
*/
say: function(message) {
return this.name + " says: " + message;
}
}
);