JSDocとは？書き方などをサンプルコードを用いてわかりやすく解説！

JavaScriptのコードを書いていて、「この関数が何をするのか忘れてしまった」「引数にどんな値を渡せばいいのか分からなくなった」という経験はありませんか？また、チーム開発では、他の人が書いたコードを理解するのに時間がかかることもあると思います。

そんな問題を解決してくれるのが『JSDoc』です。JSDocは、JavaScriptコードにコメント形式で記述することで、コードの意味や型情報を分かりやすくする仕組みです。

この記事では『JSDoc』について、以下の内容を図やサンプルコードを用いてわかりやすく解説します。

  • JSDocとは
  • JSDocの書き方
  • JSDocのメリットとデメリット
  • TypeScriptではJSDocを記述する必要があるか

JSDocとは

JSDocとは

JSDocは、JavaScriptコードにコメント形式で記述するドキュメンテーションの仕組みです。

変数、オブジェクト、関数、引数、戻り値、クラスなどの情報をコメント形式で記述することで、コードの可読性が向上します。

また、呼び出し元でカーソルを合わせると、ツールチップでヒントが提供されるようになったり、JSDocコメントを基に、TypeDoc等を使ってHTML形式のドキュメントを生成したりすることができます。

JSDocの用途

  • 可読性の向上
    • コードに説明が加わることで、将来コードを読む人（自分含む）が内容を理解しやすくなります。
  • コード補完やコードヒントの表示
    • JSDoc対応のエディター（例: VSCode）では、JSDocコメントを基にコード補完やツールチップでヒントを提供してくれます。
  • ドキュメントの自動生成
    • JSDocコメントを解析して、HTML形式のドキュメントが生成可能です。

JSDocの書き方

JSDocの書き方について以下の内容を順番に説明します。

  • JSDocの基本構文
  • 変数の場合の書き方
  • 配列の場合の書き方
  • 関数の場合の書き方
  • オブジェクト（連想配列）の場合の書き方
  • クラスの場合の書き方

JSDocの基本構文

JSDocはコードの直前に書き、JSDocは、/**で始まり、*/で終わるようにします。その内部に説明やJSDocタグを記述します。

/**
 * ここに説明を書きます。
 * JSDocタグを利用して追加情報を記述します。
 */

例えば、関数の場合、以下に示すようにJSDocタグ（@paramやreturns）を使用して記述します。

/**
 * 2つの数値を加算する関数
 * @param {number} a - 足される数。
 * @param {number} b - 足す数。
 * @returns {number} 足し算の結果。
 */
function add(a, b) {
  return a + b;
}

このadd関数は数値型の引数を2つ受け取り、その結果を返すことが分かります。

変数の場合

変数の場合、@typeを使用して型や説明を記述します。

@typeの後の{}の中に変数の型(number、string、booleanなど）を書いて、その後に変数の説明を書きます。

例えば、数値型(number)の変数を定義する場合、以下のように記述します。

/**
 * @type {number} - ユーザーの年齢を表す変数。
 */
const age = 25;

文字列型(string)の変数を定義する場合は、以下のようになります。

/**
 * @type {string} - 挨拶メッセージを表す変数。
 */
const message = "Hello, JSDoc!";

配列の場合

変数の場合も@typeを使用して型や説明を記述します。

@typeの後の{}の中に配列の型(number[]、string[]、boolean[]）を書いて、その後に配列の説明を書きます。

例えば、string[]の配列を定義する場合、以下のように記述します。

/**
 * @type {string[]} - ユーザー名を表す文字列の配列
 */
const userNames = ["Alice", "Bob", "Charlie"];

関数の場合

関数の場合、最初に関数の説明を書きます。その後に@paramを使用して引数の型と説明を記述します（実際に定義された引数の数だけ@paramを書きます）。最後に@returnsを使用して、戻り値の型と説明を記述します。

/**
 * 2つの数値を加算する関数
 * @param {number} a - 足される数。
 * @param {number} b - 足す数。
 * @returns {number} 足し算の結果。
 */
function add(a, b) {
  return a + b;
}

@returns と @return はどちらもJSDocで戻り値を記述するためのタグです。どちらを使用しても同じ意味になります。好みに応じて選べますが、@returns のほうが広く使われる傾向があります。

オブジェクト（連想配列）の場合

オブジェクト（連想配列）の場合、@typedefでカスタム型を定義し、@typeを使ってカスタム型を利用します。

@typedefの後の{}の中にはObjectを書いて、その後にオブジェクトのカスタム型(ここではUser)を定義します。プロパティは@propertyを使用して型や説明を記述します。@typeの後の{}の中には@typedefで定義したカスタム型を記述します。

例えば、ユーザー情報を持つオブジェクトを定義する場合、以下のように記述します。

/**
 * @typedef {Object} User
 * @property {string} name - ユーザーの名前。
 * @property {number} age - ユーザーの年齢。
 * @property {function(): string} getDetails - ユーザーの詳細を取得するメソッド。
 */

/** @type {User} */
const user = {
  name: 'Alice',
  age: 25,
  getDetails: function () {
    return `${this.name}, ${this.age}歳`;
  },
};

メソッドの引数や戻り値をより詳しく説明したい場合、以下に示すように、@property内で@paramと@returnsを使って詳細を記述することもできます

/**
 * @typedef {Object} User
 * @property {string} name - ユーザーの名前。
 * @property {number} age - ユーザーの年齢。
 * @property {function(string): string} greet - ユーザーが挨拶をするメソッド。
 *    - @param {string} message - 挨拶のメッセージ。
 *    - @returns {string} ユーザーが返す挨拶文。
 */

/** @type {User} */
const user = {
  name: 'Alice',
  age: 25,
  greet: function (message) {
    return `${this.name} says: ${message}`;
  },
};

クラスの場合

クラスのプロパティやメソッドにもJSDocを記述できます。

/**
 * ユーザーを表すクラス。
 */
class User {
  /**
   * ユーザーを作成します。
   * @param {string} name - ユーザーの名前。
   * @param {number} age - ユーザーの年齢。
   */
  constructor(name, age) {
    /** @type {string} */
    this.name = name;
    /** @type {number} */
    this.age = age;
  }

  /**
   * ユーザーの詳細を取得します。
   * @returns {string} ユーザーの詳細情報。
   */
  getDetails() {
    return `${this.name}, ${this.age}歳`;
  }
}

JSDocのメリットとデメリット

JSDocのメリットとデメリットを以下に示します。

メリット

  • 可読性の向上
    • JSDocで型や説明が記述されているので、将来コードを読む人（自分含む）が内容を理解しやすくなる。
    • 実装しても数ヶ月後に「何をする関数だったっけ？」と考えることがあると思いますが、そういった時間を削減できる。
  • コード補完やコードヒントが表示される
    • JSDoc対応のエディター（例: Visual Studio Code）では、JSDocコメントを基にコード補完してくれます。
    • 呼び出し元でカーソルを合わせると、ツールチップでヒントが提供されます。そのため、呼び出し元に遷移することなく、関数やクラスの概要を知ることができます。
  • ドキュメントを生成できる
    • JSDocコメントを基に、専用ツール（例: TypeDocやJSDoc）を使ってHTML形式のドキュメントを生成可能です。これにより、チームメンバーやクライアントへの情報共有が容易になります。

デメリット

  • 手間が増える
    • コメントを書くための工数や行数が増えます。

TypeScriptではJSDocを記述する必要があるか

TypeScriptでは型情報が直接コードに書かれるため、JSDocを使って型情報を明示する必要はほぼありません。

JavaScriptの場合

/**
 * 2つの数値を加算する関数
 * @param {number} a - 足される数。
 * @param {number} b - 足す数。
 * @returns {number} 足し算の結果。
 */
function add(a, b) {
  return a + b;
}

TypeScriptの場合

/**
 * 2つの数値を加算する関数
 * @param  a - 足される数。
 * @param  b - 足す数。
 * @returns 足し算の結果。
 */
function add(a: number, b: number): number {
  return a + b;
}

しかし、以下のケースでは、JSDocが役立ちます。

  • JavaScriptプロジェクトとの互換性
    • JavaScriptとTypeScriptが混在するプロジェクトでは、JSDocは型情報等を伝えるドキュメントとして利用できます。
  • 型情報以外の記述
    • 型以外の情報（例えば、引数の説明、関数の説明、使用上の注意など）を記述するためにJSDocを利用できます。

本記事のまとめ

この記事では『JSDoc』について、以下の内容を説明しました。

  • JSDocを使えば、コードの可読性が向上する。
  • 型情報や説明を記述することで、コード補完やヒント表示が便利になる。
  • ドキュメントの自動生成が可能で、ドキュメント作成の手間を省ける。

お読み頂きありがとうございました。