JSDoc 中文网

语法

¥Syntax

@alias <aliasNamepath>

概述

¥Overview

@alias 标记使 JSDoc 将对成员的所有引用视为该成员具有不同的名称。如果你在内部函数中定义类，则此标记特别有用；在这种情况下，你可以使用 @alias 标签来告诉 JSDoc 该类如何在你的应用中公开。

¥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.

虽然@alias 标签听起来与@name 标签类似，但这些标签的行为却截然不同。@name 标签告诉 JSDoc 忽略与注释关联的任何代码。例如，当 JSDoc 处理以下代码时，它会忽略 bar 的注释附加到函数的事实：

¥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() {}

@alias 标记告诉 JSDoc 假装成员 A 实际上名为成员 B。例如，当 JSDoc 处理以下代码时，它识别出 foo 是一个函数，然后在文档中将 foo 重命名为 bar：

¥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() {}

示例

¥Examples

假设你使用的类框架希望你在定义类时传入构造函数。你可以使用 @alias 标签告诉 JSDoc 该类将如何在你的应用中公开。

¥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.

在下面的示例中，@alias 标记告诉 JSDoc 将匿名函数视为类 "trackr.CookieManager" 的构造函数。在函数内，JSDoc 解释相对于 trackr.CookieManager 的 this 关键字，因此 "value" 方法具有名称路径 "trackr.CookieManager#value"。

¥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".

将 @alias 与匿名构造函数一起使用
Klass('trackr.CookieManager',

    /**

     * @class

     * @alias trackr.CookieManager

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

);

你还可以将 @alias 标记与在立即调用函数表达式 (IIFE) 中创建的成员一起使用。@alias 标签告诉 JSDoc 这些成员暴露在 IIFE 范围之外。

¥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.

对命名空间的静态成员使用@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 标记的替代。

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

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