jsdoc块和内联标签

原文：http://usejsdoc.org/about-block-inline-tags.html

概览

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

• 块标签，这是在一个JSDoc注释的最高级别。
• 行内标签，这是文本中的块标签或说明。

块标签通常会提供有关您的代码的详细信息，如函数接受的参数。行内标签通常链接到文件的其他部分，类似于HTML中的锚标记（）。

块标签总是以符号（@）开头。每块标记后面必须跟一个换行符，在JSDoc注释中除了最后一块标记。

行内标签也以符号开头。然而，内联标签及其文本必须用花括号（{and}）。该{表示行内标签的开始，而}表示行内标签的结束。如果你的标签的文本中包括右花括号（}），则必须用领先的反斜线（\）进行转义。你并不需要使用一个换行符在内联标签后。

大多数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) {
    // ...
};