@alias¶

.. @alias::¶

语法

@alias <aliasNamepath>

概述

The @alias tag causes JSDoc to treat all references to a member as if the member had a different name. This tag is especially useful if you define a class within an inner function; in this case, you can use the @alias tag to tell JSDoc how the class is exposed in your app.

While the @alias tag may sound similar to the @name tag, these tags behave very differently. The @name tag tells JSDoc to ignore any code associated with the comment. For example, when JSDoc processes the following code, it ignores the fact that the comment for bar is attached to a function:

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

The @alias tag tells JSDoc to pretend that Member A is actually named Member B. For example, when JSDoc processes the following code, it recognizes that foo is a function, then renames foo to bar in the documentation:

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

示例

Suppose you are using a class framework that expects you to pass in a constructor function when you define a class. You can use the @alias tag to tell JSDoc how the class will be exposed in your app.

In the following example, the @alias tag tells JSDoc to treat the anonymous function as if it were the constructor for the class “trackr.CookieManager”. Within the function, JSDoc interprets the this keyword relative to trackr.CookieManager, so the “value” method has the namepath “trackr.CookieManager#value”.

Using @alias with an anonymous constructor function¶

Klass('trackr.CookieManager',

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

);

You can also use the @alias tag with members that are created within an immediately invoked function expression (IIFE). The @alias tag tells JSDoc that these members are exposed outside of the IIFE’s scope.

Using @alias for static members of a namespace¶

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

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

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

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

For members that are defined within an object literal, you can use the @alias tag as an alternative to the [@lends]lends tag.

Using @alias for an object literal¶

// 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;
})();