[Typescript] JSDocを作る

はじめに

JSDocを使用すると、関数、クラス、メソッド、パラメータ、戻り値などに関する情報をコメントとして記述できます。これにより、コード自体がその動作や使用方法を説明するドキュメントとして機能し、後からコードを読む人が理解しやすくなります。

Typescript初めての方下記がおすすめです。

実装

type

TypeScriptでは型エイリアスやインターフェースを定義する際にJSDocコメントを使用できます。これは、その型が何を表しているのか、どのような場合に使用されるのかを説明するのに役立ちます。

example.d.ts

/**
 * ユーザーを表す型。
 * @typedef {Object} User
 * @property {number} id ユーザーの一意の識別子。
 * @property {string} name ユーザーのフルネーム。
 * @property {string} email ユーザーのメールアドレス。
 */
export type User = {
  id: number;
  name: string;
  email: string;
};

function

関数にJSDocコメントを付けることで、その関数が何をするのか、どのようなパラメータを取り、何を返すのかを明確にすることができます。

example.ts

/**
 * 二つの数値の合計を計算します。
 * @param {number} a 最初の数値。
 * @param {number} b 二番目の数値。
 * @returns {number} 二つの数値の合計。
 */
const add = (x: number, y: number): number => {
  return x + y;
};

関数にカーソルを合わせると説明文が出ます。

class

クラスとそのメソッドにJSDocコメントを付けることで、クラスの目的、使用方法、各メソッドの機能を文書化できます。

example.ts

/**
 * Personクラスは人物を表します。
 */
class Person {
  /**
   * Personのインスタンスを作成します。
   * @param {string} name 人物の名前。
   * @param {number} age 人物の年齢。
   */
  constructor(name, age) {
    /** @type {string} */
    this.name = name;
    /** @type {number} */
    this.age = age;
  }

  /**
   * 人物の自己紹介をします。
   * @returns {string} 自己紹介の文。
   */
  introduce() {
    return `こんにちは、私の名前は${this.name}です。${this.age}歳です。`;
  }
}

まとめ

この記事では、JSDocを使用してTypeScriptコードにドキュメントコメントを追加する方法とその利点について説明しました。JSDocは、関数、クラス、メソッド、パラメータ、戻り値などのコード要素に対して豊富な情報を提供することができる強力なツールです。これにより、コードが自己文書化され、後からコードを読む人がその動作や使用方法を容易に理解できるようになります。