语法

🌐 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 将 this 关键字解释为相对于 trackr.CookieManager，因此 "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".

Klass('trackr.CookieManager',

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

);

你也可以在通过立即执行函数表达式（IIFE）创建的成员上使用 @alias 标签。@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.

/** @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.

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

Related links

• @lends
• @name