@use JSDoc

语法

@variation <variationNumber>

概述

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

变体可帮助 JSDoc 区分具有相同长名称的不同符号。例如，如果将“@variation 2”添加到 Widget 类的 JSDoc 注释中，“{@link Widget(2)}”将引用该类，“{@link Widget}”将引用命名空间。或者，可以在指定符号的标签（例如 @alias 或 @name）时包含变体（例如，“@alias Widget(2)”）。

只要值和长名称的组合产生长名称的全局唯一版本，就可以使用 @variation 标签提供任何值。最佳做法是使用可预测的模式来选择值，这将使你更轻松地记录代码。

示例

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

使用 @variation 标签
/**
 * 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
};