块和内联标签

概述

JSDoc支持两种不同的标记:

• 块标签, 它们位于JSDoc评论的顶层.

• 内联标记, 它们位于块标记或描述的文本中.

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

块标记总是以at符号开头(@). 除了JSDoc注释中的最后一个块标记之外, 每个块标记后面必须跟一个换行符.

内联标记也以at符号开头. 但是, 内联标签及其文本必须用大括号括起来({ 和 }). { 表示内联标记的开头, } 表示内联标记的结尾. 如果你的标签的文本包含一个结束大括号(}), 你必须使用前导反斜杠(\)来转义它. 内联标记后不需要使用换行符.

Most JSDoc tags are block tags. In general, when this site refers to “JSDoc tags,” we really mean “block tags.”

示例

In the following example, @param is a block tag, and {@link} is an inline tag:

Block and inline tags in JSDoc comments

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

您可以在说明中使用内联标记, 如上所示, 也可以在块标记内使用, 如下所示:

Inline tag used within a block tag

/**
 * 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注释中使用多个块标记时, 它们必须用换行符分隔:

Multiple block tags separated by line breaks

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