@alias

Оглавление

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

Синтаксис

@alias <aliasNamepath>

Обзор

Тег @alias заставляет JSDoc интерпретировать все ссылки на член как если бы член имел другое имя. Этот тег особенно полезен, если вы определены класс внутри вложенной функции; в этом случае вы можете использовать тег @alias, чтобы сообщить JSDoc, как класс экспонируется в вашем приложении.

Хотя тег @alias может показаться похожим на тег @name, эти теги ведут себя очень по-разному. Тег @name сообщает JSDoc игнорировать любой код, связанный с комментарием. Например, когда JSDoc обрабатывает следующий код, он игнорирует тот факт, что комментарий для bar прикреплён к функции:

/**
 * Bar function.
 * @name bar
 */
function foo() {}

Тег @alias сообщает JSDoc, что член A фактически называется членом B. Например, когда JSDoc обрабатывает следующий код, он распознаёт, что foo является функцией, а затем переименовывает foo в bar в документации:

/**
 * Bar function.
 * @alias bar
 */
function foo() {}

Примеры

Предположим, вы используете фреймворк класса, который ожидает, что вы передадите конструктор функции при определении класса. Вы можете использовать тег @alias, чтобы сообщить JSDoc, как класс будет экспонирован в вашем приложении.

В следующем примере тег @alias сообщает JSDoc интерпретировать анонимную функцию как конструктор класса "trackr.CookieManager". Внутри функции JSDoc интерпретирует ключевое слово this относительно trackr.CookieManager, поэтому метод "value" имеет путь именования "trackr.CookieManager#value".

Klass('trackr.CookieManager',

    /**
     * @class
     * @alias trackr.CookieManager
     * @param {Object} kv
     */
    function(kv) {
        /** The value. */
        this.value = kv;
    }

);

Вы также можете использовать тег @alias с членами, созданными внутри выражения функции с немедленным вызовом (IIFE). Тег @alias сообщает JSDoc, что эти члены экспонированы за пределами области видимости IIFE.

/** @namespace */
var Apple = {};

(function(ns) {
    /**
     * @namespace
     * @alias Apple.Core
     */
    var core = {};

    /** Documented as Apple.Core.seed */
    core.seed = function() {};

    ns.Core = core;
})(Apple);

Для членов, определённых внутри объекта литерала, вы можете использовать тег @alias в качестве альтернативы тегу @lends.

// Documenting objectA with @alias

var objectA = (function() {

    /**
     * Documented as objectA
     * @alias objectA
     * @namespace
     */
    var x = {
        /**
         * Documented as objectA.myProperty
         * @member
         */
        myProperty: 'foo'
    };

    return x;
})();

// Documenting objectB with @lends

/**
 * Documented as objectB
 * @namespace
 */
var objectB = (function() {

    /** @lends objectB */
    var x = {
        /**
         * Documented as objectB.myProperty
         * @member
         */
        myProperty: 'bar'
    };

    return x;
})();

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

• @name
• @lends