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