ブロックタグとインラインタグ

概要

JSDoc は 2 種類のタグをサポートしています。

• ブロックタグは、JSDoc コメントの先頭に配置されます。
• インラインタグは、ブロックタグまたは説明のテキスト内にあります。

ブロックタグは通常、関数で受け入れるパラメータなどのコードに関する詳細情報を提供します。インラインタグは通常、HTML のアンカータグ (<a>) と同様に、ドキュメントの他の部分にリンクします。

ブロックタグは必ずアットマーク (@) で始まります。各ブロックタグに続けて改行する必要があります。最後のブロックタグを除きます。

インラインタグもアットマークで始まります。ただし、インラインタグとそのテキストは中括弧 ({ と }) で囲む必要があります。{ はインラインタグの開始を示し、} はインラインタグの終了を示します。タグのテキストに中括弧 (}) が含まれる場合は、バックスラッシュ (\) でエスケープする必要があります。インラインタグの後に改行を使用する必要はありません。

ほとんどの JSDoc タグはブロックタグです。一般的に、このサイトで「JSDoc タグ」と述べている場合、実際には「ブロックタグ」を意味しています。

例

次の例では、@param はブロックタグで、{@link} はインラインタグです。

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