块级和行内标签

概述

JSDoc 支持两种不同的标签

块级标签，位于 JSDoc 注释的顶层。
行内标签，位于块级标签或描述的文本中。

块级标签通常提供有关代码的详细信息，例如函数接受的参数。行内标签通常链接到文档的其他部分，类似于 HTML 中的锚点标签 (<a>)。

块级标签始终以 at 符号 (@) 开头。每个块级标签后面都必须换行，JSDoc 注释中的最后一个块级标签除外。

行内标签也以 at 符号开头。但是，行内标签及其文本必须用花括号 ({ 和 }) 括起来。{ 表示行内标签的开始，} 表示行内标签的结束。如果标签的文本包含一个闭合花括号 (})，则必须用反斜杠 (\) 转义它。行内标签后不需要换行。

大多数 JSDoc 标签都是块级标签。一般来说，当本网站提到“JSDoc 标签”时，我们实际上指的是“块级标签”。

示例

在以下示例中，@param 是块级标签，{@link} 是行内标签

JSDoc 注释中的块级和行内标签

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