语法

🌐 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，该对象字面量的所有成员名称都被“借用”给名为 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;
        }
    }
);

Related links

• @borrows
• @constructs