@variation

Содержание

• Синтаксис
• Обзор
• Примеры
• Связанные ссылки

Синтаксис

@variation <variationNumber>

Обзор

Иногда ваш код может содержать несколько символов с одинаковым длинным именем. Например, у вас может быть как глобальный класс, так и пространство имён верхнего уровня, называемое Widget. В таких случаях, что означает "{@link Widget}" или "@memberof Widget"? Глобальное пространство имен или глобальный класс?

Вариации помогают JSDoc различать разные символы с одинаковым длинным именем. Например, если к комментарию JSDoc для класса Widget добавлен "@variation 2", то "{@link Widget(2)}" будет ссылаться на класс, а "{@link Widget}" — на пространство имен. Кроме того, вы можете включить вариацию при указании символа с помощью тегов, таких как @alias или @name (например, "@alias Widget(2)").

Вы можете использовать любое значение с тегом @variation, пока комбинация значения и длинного имени приводит к глобально уникальной версии длинного имени. В качестве рекомендации рекомендуется использовать предсказуемый шаблон для выбора значений, что упростит документирование вашего кода.

Примеры

В следующем примере тег @variation используется для различения класса Widget и пространства имен Widget.

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

Связанные ссылки

• @alias
• @name