JSDoc中文文档(@use JSDoc)

JSDoc @alias 标签

目录

语法

@alias <aliasNamepath>

概述

@alias标签标记成员有一个别名。如果该成员有不同的名称，JSDoc把所有引用作为这个成员。如果你在一个内部函数中定义一个类的时候，这个标签是非常有用的;在这种情况下，您可以使用@alias标签告诉JSDoc，这个类如何在您的应用程序中暴露出来。

虽然@alias标签听起来类似于@name标签，但是他们的行为非常不同。@name标签告诉JSDoc忽略与注释关联的所有代码。例如，当JSDoc处理下面的代码的时候，它忽略了bar的注释关联到一个foo函数： 

/**
 * 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将this关键字解释为trackr.CookieManager，因此，“value”方法的namepath(名称路径)为“trackr.CookieManager＃value”。

示例: 匿名的构造函数使用@alias
Klass('trackr.CookieManager',

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

);

您也可以在一个立即调用的函数表达式（IIFE）中创建的成员中使用@alias标签。@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;
})();