ES 2015 モジュール

JSDoc 3 は、ECMAScript 2015 仕様に従うモジュールのドキュメントを作成することを可能にします。ES 2015 モジュールは、JSDoc 3.4.0 以降でサポートされます。

モジュール識別子

ES 2015 モジュールのドキュメントを作成する場合、モジュールの識別子をドキュメント化するために、@module タグ を使用します。たとえば、ユーザーが import * as myShirt from 'my/shirt' を呼び出してモジュールをロードする場合、@module my/shirt タグを含む JSDoc コメントを作成します。

@module タグを値なしで使用すると、JSDoc はファイルパスに基づいて正しいモジュール識別子を推測しようとします。

別の JSDoc コメントからモジュールを参照するために JSDoc の名前パスを使用する場合、プレフィックス module: を追加する必要があります。たとえば、my/pants モジュールのドキュメントが my/shirt モジュールへのリンクにする場合、@see タグ を使用して次のように my/pants をドキュメント化できます。

/**
 * Pants module.
 * @module my/pants
 * @see module:my/shirt
 */

同様に、モジュールの各メンバーの名前パスは、モジュール名の後に module: で始まります。たとえば、my/pants モジュールが Jeans クラスをエクスポートし、Jeans に hem というインスタンスメソッドがある場合、インスタンスメソッドのロングネームは module:my/pants.Jeans#hem になります。

エクスポートされた値

次の例は、ES 2015 モジュールでさまざまな種類のエクスポートされた値をドキュメント化する手順を示しています。ほとんどの場合、エクスポートされた値を定義する export ステートメントに JSDoc コメントを追加するだけです。別の名前で値をエクスポートする場合は、export ブロック内でエクスポートされた値をドキュメント化できます。

/** @module color/mixer */

/** The name of the module. */
export const name = 'mixer';

/** The most recent blended color. */
export var lastColor = null;

/**
 * Blend two colors together.
 * @param {string} color1 - The first color, in hexadecimal format.
 * @param {string} color2 - The second color, in hexadecimal format.
 * @return {string} The blended color.
 */
export function blend(color1, color2) {}

// convert color to array of RGB values (0-255)
function rgbify(color) {}

export {
    /**
     * Get the red, green, and blue values of a color.
     * @function
     * @param {string} color - A color, in hexadecimal format.
     * @returns {Array.<number>} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}

関連リンク

• @module
• 名前パスを JSDoc で使用