JSDocとは

JSDocは、JavaScriptのソースコード内にアノテーション（注釈）を
記述するためのマークアップ言語です。
この規約に沿ってコメントを記述することで、
コードから自動的にAPIドキュメントを生成したり、
エディタのコード補完や型チェック機能を強化したりすることができます。

主な目的とメリット

• ドキュメントの自動生成 📝
  JSDocで記述されたコメントは、ツール（例: JSDoc 3）を
  使ってHTML形式のAPIドキュメントとして出力できます。
  これにより、コードとドキュメントの同期を保ちやすくなります。

• コードの可読性向上 👀
  関数や変数の役割、引数の型、返り値などが明確になり、他の開発者がコードを理解しやすくなります。

• エディタによる開発支援 💻
  Visual Studio Codeなどの多くのコードエディタはJSDocを解釈し、
  関数の引数に関する情報表示、コード補完、
  さらにはTypeScriptのような静的な型チェック機能を提供します。

/**
 * 2つの数値を加算して結果を返します。
 *
 * @param {number} a - 最初の数値。
 * @param {number} b - 2番目の数値。
 * @returns {number} 2つの数値の合計。
 */
function add(a, b) {
  return a + b;
}

この例では、以下のタグが使用されています。

• @param {<型>}: 関数の引数とその型、説明を定義します。

• @returns {<型>}: 関数の返り値の型と説明を定義します。

JSDocを記述することで、この add 関数をエディタで呼び出す際に、
引数 a と b が数値(number)であることや、
関数が数値(number)を返すことがツールチップで表示されるようになり、
開発効率が向上します。