【解説】JavaScriptのJSDocコメントの使い方

記事内に広告を含みます

【解説】JavaScriptのJSDocコメントの使い方
【解説】JavaScriptのJSDocコメントの使い方：まとめ

【解説】JavaScriptのJSDocコメントの使い方

JSDocコメントは、JavaScriptのコードに説明などを記述できる特殊なコメント形式のこと。

「/** */」と下記、その中に説明をコメントで記述します。

/**
 * 説明内容
 * 説明内容
 */

直下のコードに適用されるのが特徴です。

そんなJSDocコメントの主なタグがこちら。

@type

@param と @returns

@see

@author

順に解説してきます。

@type

@typeは変数やオブジェクトの型を記述します。

{}で型を書いて、その後に説明をいれます。

/** 
 * @type {型} 説明
 */

/** 
 * @type {string}
 * ユーザーの名前を保持する変数
 */
const userName = "Tanaka";

/** 
 * @type {number}
 * 年齢を示す変数
 */
let age = 20;

@param と @returns

@paramは関数の引数を、
@returnsは関数の戻り値を説明します。

型、名前、役割を記述します。

書き方はこんな感じ↓

/**
 * 関数の説明
 * @param {型} 引数1 - 説明
 * @param {型} 引数2 - 説明
 * @returns {型} - 説明
 */

function 関数名(引数1, 引数2) {
  return 〜〜〜;
}

ちなみにですが、一番上に関数自体の説明を記述することもあります。

実際に使ってみたコードがこちら。

/**
 * ユーザーの情報をフォーマットします。
 * @param {string} name - ユーザーの名前
 * @param {number} age - ユーザーの年齢
 * @returns {string} - フォーマットされたユーザー情報
 */
function testUser(name, age) {
  return `名前は: ${name}, 年齢は: ${age}`;
}

// 使用例
console.log(testUser("Tanaka", 20)); // 名前は: Tanaka, 年齢は: 20

@see

@seeは関連するドキュメントやコード、資料やサイトのリンクを記述します。

/**
 * @see https:~~
 */

例とするコードがこちら。

/**
 * 配列内の最大値を取得
 * @param {number[]} nums - 数値の配列
 * @returns {number} - 配列内の最大値
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max
 */
function getMaxValue(nums) {
  return Math.max(...nums);
}

// 使用例
console.log(getMaxValue([1, 2, 3, 4, 5])); // 5