语法

🌐 Syntax

@variation <variationNumber>

概述

🌐 Overview

有时你的代码可能包含多个具有相同 longname 的符号。例如，你可能同时有一个全局类和一个顶层命名空间，名字都叫 Widget。在这种情况下，"{@link Widget}" 或 "@memberof Widget" 是指全局命名空间，还是全局类？

🌐 Sometimes your code may include multiple symbols with the same longname. For example, you might have both a global class and a top-level namespace called Widget. In cases such as these, what does "{@link Widget}" or "@memberof Widget" mean? The global namespace, or the global class?

变体帮助 JSDoc 区分具有相同 longname 的不同符号。例如，如果在 Widget 类的 JSDoc 注释中添加 "@variation 2"，"{@link Widget(2)}" 将指向该类，而 "{@link Widget}" 将指向命名空间。或者，你可以在使用诸如 @别名 或 @name 的标签指定符号时包括变体（例如 "@alias Widget(2)"）。

🌐 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 or @name (for example, "@alias Widget(2)").

你可以为 @variation 标签提供任何值，只要该值与 longname 的组合能够生成 longname 的全球唯一版本。作为最佳实践，请使用可预测的模式来选择这些值，这将使你更容易记录代码。

🌐 You can provide any value with the @variation tag, as long as the combination of the value and the longname results in a globally unique version of the longname. As a best practice, use a predictable pattern for choosing the values, which will make it easier for you to document your code.

示例

🌐 Examples

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

🌐 The following example uses the @variation tag to distinguish between the Widget class and the Widget namespace.

/**
 * 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
};

Related links

• @alias
• @name