シンプルな関数のJSDoc

JSDocでシンプルな関数をドキュメント化する

JSDocの最も一般的な使用法は、パラメータと戻り値を持つ基本的な関数のドキュメント化です。適切にドキュメント化された関数は、他の開発者（と将来の自分自身）に、何をするか、何を期待するか、何を返すかを伝えます。

シグネチャの例

function calculateArea(width: number, height: number): number

生成されるJSDoc

/**
 * 長方形の面積を計算します。
 *
 * @param {number} width - 長方形の幅（ピクセル単位）。
 * @param {number} height - 長方形の高さ（ピクセル単位）。
 * @returns {number} 計算された面積（width * height）。
 */

主要なタグ

タグ	目的
@param	関数パラメータの型と説明をドキュメント化
@returns	戻り値とその型を説明

ベストプラクティス

• 説明は三人称の動詞で始める（「Calculates」「Returns」「Validates」）
• パラメータの説明に単位や制約を含める
• 説明でエッジケースに言及する（例：「いずれかの次元が負の場合は0を返す」）
• 最初の行は簡潔に — 詳細は追加行で

JSDoc vs TSDoc

JSDocスタイルでは型は波括弧に含まれます：@param {number} width。TSDocスタイルではTypeScriptが型を提供するため型は省略されます：@param width。ジェネレーターは1つのトグルで両方を処理します。