@lends

Содержание

• Синтаксис
• Обзор
• Примеры
• Связанные ссылки

Синтаксис

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

Связанные ссылки

• @borrows
• @constructs