@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
};