@use JSDoc

语法

@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 不会识别此代码创建了一个具有两个方法的 Person 类。要记录这些方法，我们必须在对象字面量之前立即在文档注释中使用 @lends 标记。@lends 标记告诉 JSDoc 该对象字面量的所有成员名称都被“借给”名为 Person 的变量。我们还必须向每个方法添加注释。

以下示例使我们更接近想要的结果

记录为静态方法
/** @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 标记，否则将记录两个类。

使用构造函数记录
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;
        }
    }
);