@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”方法具有 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 的作用域之外公开。

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