语法
¥Syntax
@lends <namepath>
概述
¥Overview
@lends 标签允许你记录对象字面量的所有成员，就好像它们是具有给定名称的符号的成员一样。如果你将对象字面量传递到从其成员创建命名类的函数中，你可能需要执行此操作。
¥The @lends tag allows you to document all the members of an object literal as if they were members
of a symbol with the given name. You might want to do this if you are passing an object literal into
a function that creates a named class from its members.
示例
¥Examples
在此示例中，我们希望使用辅助函数创建一个名为 Person 的类，以及名为 initialize 和 say 的实例方法。这类似于一些流行框架处理类创建的方式。
¥In this example, we want to use a helper function to make a class named Person, along with
instance methods named initialize and say. This is similar to how some popular frameworks
handle class creation.
// 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 将无法识别此代码创建了一个具有两个方法的 Person 类。为了记录这些方法，我们必须在文档注释中紧邻对象字面量之前使用 @lends 标记。@lends 标记告诉 JSDoc 该对象字面量的所有成员名称都是 "loaned" 到名为 Person 的变量。我们还必须为每个方法添加注释。
¥Without any comments, JSDoc won't recognize that this code creates a Person class with two
methods. To document the methods, we must use a @lends tag in a doc comment immediately before the
object literal. The @lends tag tells JSDoc that all the member names of that object literal are
being "loaned" to a variable named Person. We must also add comments to each of the methods.
下面的例子让我们更接近我们想要的：
¥The following example gets us closer to what we want:
/** @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 类的实例。因此，我们通过将方法借给类的原型来稍微改变一下：
¥Now the functions named initialize and say will be documented, but they appear as static methods
of the Person class. That is possibly what you meant, but in this case we want initialize and
say to belong to the instances of the Person class. So we change things slightly by lending the
methods to the class's prototype:
/** @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 标记，否则将记录两个类。
¥One final step: Our class framework uses the loaned initialize function to construct Person
instances, but a Person instance does not have its own initialize method. The solution is to add
the @constructs tag to the loaned function. Remember to remove the @class tag as well, or else
two classes will be documented.
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;
}
}
);