@use JSDoc

語法

@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 會相對於 trackr.CookieManager 來詮釋 `this` 關鍵字，因此 "value" 方法的名稱路徑為 "trackr.CookieManager#value"。

使用 @alias 與匿名建構函式
Klass('trackr.CookieManager',

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

);

您也可以將 @alias 標籤與在立即呼叫函式表達式 (IIFE) 中建立的成員一起使用。@alias 標籤會告訴 JSDoc 這些成員在 IIFE 的範圍之外公開。

將 @alias 用於名稱空間的靜態成員
/** @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 標籤的替代方案。

將 @alias 用於物件文字
// 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;
})();