@lends

.. @lends::

语法

@lends <namepath>

概述

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.

示例

在这个例子中, 我们想要使用一个辅助函数来创建一个名为``Person``的类, 以及名为``initialize``和``say``的实例方法. 这类似于一些流行的框架处理类创建的方式.

Example class

// 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;
        }
    }
);

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:

Documented as static methods

/** @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``类的实例. 所以我们通过将方法借给类的原型来稍微改变一下:

Documented as instance methods

/** @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;
        }
    }
);

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.

Documented with a constructor

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;
        }
    }
);