块标签和内联标签

概述

🌐 Overview

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

🌐 JSDoc supports two different kinds of tags:

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

块标签通常提供有关你的代码的详细信息，例如函数接受的参数。内联标签通常链接到文档的其他部分，类似于 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.

块标签总是以艾特符号（@）开头。每个块标签后必须跟一个换行，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.

行内标签也以@符号开始。然而，行内标签及其文本必须包含在大括号中（{ 和 }）。{ 表示行内标签的开始，} 表示行内标签的结束。如果标签的文本包括闭合大括号（}），则必须在前面加上反斜杠进行转义（\）。行内标签后不需要使用换行符。

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