块标签和内联标签

概述

¥Overview

JSDoc 支持两种不同类型的标签：

¥JSDoc supports two different kinds of tags:

• 块标签，位于 JSDoc 注释的顶层。

  ¥Block tags, which are at the top level of a JSDoc comment.

• 内联标签，位于块标签或描述的文本内。

  ¥Inline tags, which are within the text of a block tag or a description.

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

¥Block tags usually provide detailed information about your code, such as the parameters that a function accepts. Inline tags usually link to other parts of the documentation, similar to the anchor tag (<a>) in HTML.

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

¥Block tags always begin with an at sign (@). Each block tag must be followed by a line break, with the exception of the last block tag in a JSDoc comment.

内联标签也以 at 符号开头。但是，内联标记及其文本必须括在大括号中（{ 和 }）。{ 表示内联标记的开始，} 表示内联标记的结束。如果标签的文本包含右大括号 (})，则必须使用前导反斜杠 (\) 将其转义。内联标记后不需要使用换行符。

¥Inline tags also begin with an at sign. However, inline tags and their text must be enclosed in curly braces ({ and }). The { denotes the start of the inline tag, and the } denotes the end of the inline tag. If your tag's text includes a closing curly brace (}), you must escape it with a leading backslash (\). You do not need to use a line break after inline tags.

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

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

示例

¥Examples

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

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

/**

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

你可以在描述中使用内联标签（如上所示），或在块标签内使用内联标签（如下所示）：

¥You can use inline tags within a description, as shown above, or within a block tag, as shown below:

/**

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

¥When you use multiple block tags in a JSDoc comment, they must be 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) {
    // ...
};