Блочные и инлайновые теги

Содержание

• Обзор
• Примеры

Обзор

JSDoc поддерживает два разных типа тегов:

• Блочные теги, которые находятся на верхнем уровне комментария JSDoc.
• Инлайновые теги, которые находятся внутри текста блочного тега или описания.

Блочные теги обычно предоставляют подробную информацию о вашем коде, например, о параметрах, которые принимает функция. Инлайновые теги обычно устанавливают ссылки на другие части документации, аналогично тегу якоря (<a>) в HTML.

Блочные теги всегда начинаются со знака @ (@). Каждый блочный тег должен быть после него перенос строки, за исключением последнего блочного тега в комментарии JSDoc.

Инлайновые теги также начинаются со знака @. Однако, инлайновые теги и их текст должны быть заключены в фигурные скобки ({ и }). { обозначает начало инлайнового тега, а } обозначает конец инлайнового тега. Если текст вашего тега содержит закрывающую фигурную скобку (}), вы должны экранировать её ведущим обратным слэшем (\). Вам не нужно использовать перенос строки после инлайновых тегов.

Большинство тегов JSDoc являются блочными тегами. В целом, когда на этом сайте упоминаются «теги JSDoc», имеется в виду «блочные теги».

Примеры

В следующем примере @param — это блочный тег, а {@link} — инлайновый тег:

/**
 * Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
 *
 * @param {string} color - The shoe's color.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

Вы можете использовать инлайновые теги внутри описания, как показано выше, или внутри блочного тега, как показано ниже:

/**
 * Set the shoe's color.
 *
 * @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
 * value of {@link SHOE_COLORS}.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

Когда вы используете несколько блочных тегов в комментарии JSDoc, они должны быть разделены переносами строк:

/**
 * Set the color and type of the shoelaces.
 *
 * @param {LACE_COLORS} color - The shoelace color.
 * @param {LACE_TYPES} type - The type of shoelace.
 */
Shoe.prototype.setLaceType = function(color, type) {
    // ...
};