TypeScript コメント

1. Doc コメントの必要性
2. TSDoc を使用して TypeScript で API ドキュメントを生成する

この記事は、TypeScript のドキュメント コメントに関するものです。

Doc コメントの必要性

ドキュメント コメントは、ほとんどのプログラミング言語で見ることができます。 その主な目的は、指定されたコードベースのドキュメントを生成することです。

JavaDoc を使用して Java でドキュメントを生成し、JSDoc は JavaScript の API ドキュメント ジェネレーターです。 TypeScript は TSDoc を使用して API ドキュメントを生成します。

TSDoc を使用して TypeScript で API ドキュメントを生成する

TSDoc は、コードベースにコメントする方法をプログラマーに指示する仕様です。 ツールが API ドキュメントを生成し、TypeScript コードベースのメタデータを作成できるようにします。

Microsoft TypeScript チームは、TSDoc 仕様を維持しています。 JSDoc では、アノテーションを使用して型を明示的に指定する必要があります。

TypeScript は型付き言語であるため、TSDoc で注釈を使用する必要はなく、手間をかけずにより有益なドキュメントを生成するのに役立ちます。

TSDoc コメントは、次に示すように 2つのアスタリスクで始まります。

/**
*
*
*/

また、以下に示すように、パラメーター、戻り値の型などの特別な情報を指定するために @ 注釈マークを提供します。

export class Square {
    /**
     * @Returns the area of the given square.
     *
     * @param width  - width of the square
     * @param height - the height of the square
     * @returns The multiplication of `width` and `height`.
     */
    static calculateArea(width: number, height: number): number {
      return width * height;
    }
  }

Visual Studio Code を使用して API ドキュメントを生成する

doc コメントは 2つのアスタリスクで始まり、続いています。 @Returns, @param アノテーションは、コードベースに関する追加情報を提供します。

Visual Studio Code を使用して、生成された calculateArea 関数の API ドキュメントを表示できます。

TypeDoc を使用して TSDoc コメントを HTML ドキュメントに変換する

TSDoc コメントを使用して HTML ドキュメントを生成することもできます。 次に、TypeDoc ユーティリティ ツールを使用して、TSDoc コメントをレンダリングされた HTML ドキュメントに変換する必要があります。

まず、以下に示すように typedoc をインストールすることが必須です。

npm install --save-dev typedoc

次に、typedoc コマンドライン ユーティリティを使用して HTML ドキュメントを簡単に生成できます。

typedoc --out docs .

さまざまなツールが、TypeScript コードで TSDoc コメントを使用し、それらを解析して、API ドキュメント、HTML ドキュメント、およびコードベースに関するその他の有用な情報を生成できます。