@variation

.. @variation::

语法

@variation <variationNumber>

概述

有时您的代码可能包含多个具有相同长名称的符号. 例如, 您可能同时拥有一个全局类和一个名为``Widget``的顶级命名空间. 在这些情况下, “{@link Widget}”或“@memberof Widget”是什么意思？全局命名空间, 还是全局类？

Variations help JSDoc distinguish between different symbols with the same longname. For example, if “@variation 2” is added to the JSDoc comment for the Widget class, “{@link Widget(2)}” will refer to the class, and “{@link Widget}” will refer to the namespace. Alternatively, you can include the variation when you specify the symbol’s with tags such as [@alias]alias or [@name]name (for example, “@alias Widget(2)”).

您可以使用@variation标记提供任何值, 只要value和longname的组合产生全名唯一的longname版本即可. 作为最佳实践, 使用可预测的模式来选择值, 这将使您更容易记录代码.

示例

以下示例使用@variation标记来区分Widget类和Widget命名空间.

Using the @variation tag

/**
 * The Widget namespace.
 * @namespace Widget
 */

// you can also use '@class Widget(2)' and omit the @variation tag
/**
 * The Widget class. Defaults to the properties in {@link Widget.properties}.
 * @class
 * @variation 2
 * @param {Object} props - Name-value pairs to add to the widget.
 */
function Widget(props) {}

/**
 * Properties added by default to a new {@link Widget(2)} instance.
 */
Widget.properties = {
    /**
     * Indicates whether the widget is shiny.
     */
    shiny: true,
    /**
     * Indicates whether the widget is metallic.
     */
    metallic: true
};