JSDoc中文文档(@use JSDoc)

JSDoc @lends 标签

目录

语法

@lends <namepath>

概述

@lends标签允许你将一个字面量对象的所有成员标记为某个标识符（类或模块）的成员，就像他们是给定名称的标识符成员。你可能想这样做，如果你传递一个对象字面量给一个函数，创建一个成员为对象字面量的命名类。

示例

在这个例子中，我们要使用一个辅助函数创建一个名为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;
        }
    }
);

没有任何意见，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标签，否则两个类将被文档化。

示例: 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;
        }
    }
);