Wikibooks

TSDoc

TSDocは、TypeScriptプロジェクトで使用されるドキュメンテーションコメントのための規格です。これにより、開発者はTypeScriptの型情報とともに、より明確かつ一貫したドキュメンテーションを作成できます。

このチュートリアルでは、TSDocの基本的な概念と使用法について説明します。具体的には、TSDocコメントの書き方、一般的なタグの使用方法、および高度なタグの使用方法について説明します。

また、TSDocの有用性とドキュメンテーションの重要性についても触れます。 このチュートリアルを読み終えると、開発者はTypeScriptプロジェクトでTSDocを使用するための知識を獲得でき、より良いドキュメンテーションを作成することができるようになります。

TSDocとは

編集

[TSDocの概要と、なぜドキュメンテーションにTSDocが使われるのかを紹介します。]

TSDocとは、TypeScriptプロジェクトで使用されるドキュメンテーションコメントのための規格です。TSDocは、JSDocをベースに作成されており、TypeScriptの型情報を利用して、より明確で正確なドキュメンテーションを作成することができます。

TSDocは、TypeScriptの型情報を活用することで、ドキュメンテーションの精度を向上させることができます。例えば、TypeScriptの型情報を利用することで、関数やメソッドの引数や戻り値の型を明確にすることができます。これにより、開発者はより正確な情報を得ることができ、コードの利用者もより理解しやすいドキュメンテーションを得ることができます。

TSDocが使用される主な理由は、ドキュメンテーションの重要性です。コードを書く際には、それがどのように動作するかを明確にすることが非常に重要です。しかし、コードが複雑になると、ドキュメンテーションを書くことが困難になることがあります。そのため、TSDocを使用することで、開発者はより簡単に正確かつ明確なドキュメンテーションを作成できます。

また、TSDocは、開発者がコードを維持するための負担を減らすこともできます。TSDocコメントを使用することで、コードが変更された場合に、ドキュメンテーションも自動的に更新されるため、手動でドキュメンテーションを更新する必要がありません。

以上のように、TSDocは、正確かつ明確なドキュメンテーションを作成することができるため、TypeScriptプロジェクトで広く使用されています。次の章では、TSDocコメントの書き方について説明します。

JSDocとTSDocの違い

編集

JSDocとTSDocは、JavaScriptとTypeScriptの両方で使用される、コードのドキュメンテーションのためのツールですが、いくつかの違いがあります。

サポートする型
JSDocは、JavaScriptの動的型付けに対応するために、型の推論や注釈にJSDocの特定の記法を使用します。一方、TSDocは、TypeScriptの静的型付けに対応するために、TypeScriptの型アノテーションと統合され、より自然な型表現が可能です。
名前解決の仕組み
JSDocは、名前解決においてモジュールシステムの仕組みを考慮しないため、複数のモジュール間で同じ名前を持つ変数や関数をドキュメント化する場合、正確な情報を提供することが難しいです。一方、TSDocは、TypeScriptの名前解決システムを活用するため、名前解決の精度が向上しています。
ツールチェーンのサポート
TSDocは、TypeScriptの型システムと統合されているため、TypeScriptによって提供されるビルドツールやエディタサポートとシームレスに連携することができます。一方、JSDocはJavaScript専用のツールであるため、TypeScriptとの統合には制限があります。
タグのサポート
TSDocは、TypeScript向けに開発されたため、TypeScriptの型システムに特化したタグがいくつか追加されています。一方、JSDocは、JavaScriptの動的型付けを考慮するため、TSDocにはないいくつかのタグがあります。
出力フォーマット
TSDocは、TypeScript向けに開発されたため、TypeScriptの型情報を含むように設計されています。一方、JSDocは、JavaScriptの動的型付けを考慮するため、型情報を含まない場合があります。また、JSDocは、様々なフォーマットに出力することができますが、TSDocは、現時点では主にHTMLとJSON形式の出力に対応しています。

TSDocのインストール

編集

TSDocは、TypeScriptプロジェクトで使用するために、npmパッケージとして提供されています。TSDocをインストールするには、以下の手順を実行します。

まず、プロジェクトのルートディレクトリで、以下のコマンドを実行します。 

npm install -g @microsoft/tsdoc

次に、tsconfig.jsonファイルを編集して、TSDocを有効にします。tsconfig.jsonファイルに以下のコードを追加します。 

{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "plugins": [
      {
        "name": "typescript-tsd",
        "config": {}
      }
    ]
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

これにより、TSDocがTypeScriptの型情報を読み込んで、ドキュメンテーションを生成するようになります。

最後に、ドキュメンテーションを生成するためのコマンドを実行します。以下のコマンドを実行すると、TSDocによってドキュメンテーションが生成されます。 

npx tsdoc

以上の手順で、TSDocがインストールされ、有効になり、ドキュメンテーションが生成されます。次の章では、TSDocコメントの書き方について説明します。

基本的なTSDocタグ

編集

[TSDocで使用される基本的なタグと、それらを使用する方法を紹介します。]

TSDocで使用される基本的なタグには、以下のものがあります。

  • @param - 関数のパラメータに関する情報を提供します。
  • @returns - 関数の戻り値に関する情報を提供します。
  • @remarks - その他の注釈を提供します。
  • @example - コード例を提供します。
  • @see - 関連するドキュメントやリソースを参照します。
  • @deprecated - 使われていないものや非推奨のものを示します。

これらのタグは、関数やクラス、メソッド、プロパティなどのドキュメンテーションに使用されます。以下は、@paramと@returnsの使用例です。 

/**
 * Adds two numbers together.
 * @param {number} x - The first number to add.
 * @param {number} y - The second number to add.
 * @returns {number} The sum of the two numbers.
 */
function addNumbers(x: number, y: number): number {
  return x + y;
}

この例では、@paramタグが2つ使用されています。各タグには、パラメータの名前と説明が含まれています。@returnsタグには、戻り値の型と説明が含まれています。

パラメータと戻り値

編集

[関数のパラメータや戻り値のドキュメンテーションについて、詳しく説明します。]

関数のパラメータや戻り値に関するドキュメンテーションは、@paramと@returnsタグを使用して記述できます。これらのタグには、パラメータや戻り値に関する情報を提供するためのいくつかの属性があります。以下は、@paramタグと@returnsタグで使用される属性の一部です。

  • name - パラメータや戻り値の名前を指定します。
  • type - パラメータや戻り値の型を指定します。
  • description - パラメータや戻り値に関する説明を提供します。
  • default - パラメータのデフォルト値を指定します。

以下は、パラメータに関するドキュメンテーションの例です。 

/**
 * Multiplies a number by a factor.
 * @param {number} number - The number to multiply.
 * @param {number} factor - The factor to multiply the number by.
 * @returns {number} The result of multiplying the number by the factor.
 */
function multiply(number: number, factor: number): number {
  return number * factor;
}

この例では、@paramタグが2つ使用されています。各タグには、パラメータの名前と説明が含まれています。

タグの詳細

編集

[TSDocで使用されるタグのうち、より詳細な説明が必要なタグについて説明します。]

タグとその機能
タグ名 説明
@param 関数のパラメーターについて説明します。パラメーターの名前と説明文を指定できます。例えば、 @param {number} x - 数値の引数 といった形で使用します。
@returns 関数が返す値について説明します。戻り値の型と説明文を指定できます。例えば、 @returns {boolean} 真偽値 といった形で使用します。
@type 変数や定数などの型について説明します。変数の名前と型を指定できます。例えば、 @type {string} name といった形で使用します。
@template ジェネリックスの型パラメーターについて説明します。型パラメーターの名前と説明文を指定できます。例えば、 @template T - ジェネリックスの型パラメーター といった形で使用します。
@example コードの例を示します。コードブロックを使って、実際のコードを記述することができます。例えば、 @example\nconst result = add(2, 3);\nconsole.log(result); といった形で使用します。
@deprecated 非推奨の要素について説明します。非推奨になった理由や代替の手段などを説明することができます。例えば、 @deprecated 代わりに といった形で使用します。
@inheritdoc 継承元のドキュメンテーションを継承することができます。継承元のドキュメンテーションに @inheritdoc を指定して、継承先でその要素を参照することができます。例えば、 @inheritdoc といった形で使用します。

カスタムタグ

編集

[TSDocで独自のカスタムタグを作成する方法を説明します。]

TSDocでは、プロジェクトのニーズに応じて独自のカスタムタグを作成することができます。カスタムタグを作成することで、プロジェクト固有の情報をドキュメンテーションに含めることができます。

カスタムタグを作成するには、TSDocの @custom タグを使用します。 @custom タグには、以下のような属性を指定できます。

  • name: カスタムタグの名前。必須。
  • kind: カスタムタグの種類。任意。
  • body: カスタムタグの説明。任意。

カスタムタグの種類としては、以下のものがあります。

  • block: 複数行にわたる説明を提供するブロックタグ。
  • inline: 一行の説明を提供するインラインタグ。
  • modifier: 他のタグの修飾子として使用されるタグ。

以下は、@custom タグを使用して独自の @example タグを作成する例です。 

/**
 * @custom
 * @name example
 * @kind block
 * @body
 * Provides an example of how to use a function or class.
 */

この例では、@example タグの名前を example に設定し、種類を block に設定しています。また、カスタムタグの説明として、Provides an example of how to use a function or class. という文を指定しています。

カスタムタグを使用する場合、TypeScriptのコンパイラにオプション --customDocTags を指定して、カスタムタグを認識させる必要があります。以下は、@example タグを使用する例です。 

/**
 * Returns the sum of two numbers.
 * @example
 * ```
 * const result = sum(1, 2);
 * console.log(result); // Output: 3
 * ```
 */
function sum(a: number, b: number): number {
  return a + b;
}

この例では、@example タグを使用して、関数の使用例を提供しています。 @example タグは、カスタムタグとして定義されているため、コンパイラに --customDocTags オプションを指定する必要があります。

ソースコードの生成

編集

[TSDocを使用して、HTMLやJSONなどの形式でソースコードのドキュメントを生成する方法を説明します。]

TSDocを使用して、ソースコードのドキュメントを生成する方法を紹介します。TSDocには、HTMLやJSONなどの形式でドキュメントを生成するためのコマンドが用意されています。

HTMLファイルの生成

編集

HTMLファイルを生成するには、TSDocに付属するtypedocコマンドを使用します。以下のコマンドを実行することで、指定されたソースコードからHTMLファイルを生成することができます。 

npx typedoc --out ./docs ./src

上記のコマンドでは、./src以下のソースコードからHTMLファイルを生成し、./docsディレクトリに出力しています。生成されたHTMLファイルは、ブラウザで開いて閲覧することができます。

JSONファイルの生成

編集

JSONファイルを生成するには、TSDocに付属するts-json-docsコマンドを使用します。以下のコマンドを実行することで、指定されたソースコードからJSONファイルを生成することができます。 

npx ts-json-docs ./src/**/*.ts --output-file ./docs/api-docs.json

上記のコマンドでは、./src以下の.tsファイルからJSONファイルを生成し、./docs/api-docs.jsonに出力しています。生成されたJSONファイルは、APIドキュメントの作成などに使用することができます。

以上が、TSDocを使用してソースコードのドキュメントを生成する方法です。生成されたドキュメントは、開発者がコードを理解するために重要な情報を提供するため、プロジェクトの品質向上に役立ちます。

== TSDocのエディタサポート == [TSDocを使用したドキュメンテーションの効果を高めるための、いくつかのエディタのプラグインや拡張機能を紹介します。] TSDocを使用することで、コードのドキュメンテーションが改善されますが、エディタサポートを使用することで、開発者はより簡単にTSDocを記述できます。以下は、TSDocをサポートするいくつかのエディタプラグインです。

  • Visual Studio Code：MicrosoftのテキストエディタであるVisual Studio Codeは、TSDocをサポートする豊富なプラグインを提供しています。例えば、「TSDoc Comments」プラグインは、TSDocコメントを簡単に作成するためのツールを提供します。
  • Atom：GitHubによって開発されたテキストエディタであるAtomも、TSDocをサポートするいくつかのパッケージを提供しています。例えば、「docblockr」パッケージは、JavaScriptやTypeScriptの関数やメソッドのTSDocコメントを簡単に作成できます。
  • JetBrains IDEs：JetBrainsのIDEであるIntelliJ IDEA、WebStorm、PhpStormなどは、TSDocをサポートするいくつかのプラグインを提供しています。例えば、「TypeDocコメント」プラグインは、TSDocコメントを簡単に生成するためのツールを提供します。

これらのエディタプラグインを使用することで、TSDocを使用したコードのドキュメンテーションがより簡単になり、開発者はより効果的にドキュメントを作成できます。

TSDocのベストプラクティス

編集

[TSDocでのドキュメンテーションのベストプラクティスを紹介し、より読みやすく、明確なコードのドキュメントを作成するためのヒントを提供します。]

TSDocを使って効果的なドキュメンテーションを作成するには、以下のベストプラクティスを遵守することが重要です。

  1. 全ての公開されたメンバーにドキュメンテーションを追加する：公開されたメソッド、クラス、関数、インターフェースなどの全てのメンバーに対して、適切なドキュメンテーションを提供することが重要です。これにより、他の開発者がコードを理解し、使用するのが容易になります。
  2. メソッドと関数には、パラメータと戻り値の説明を含める：関数やメソッドをドキュメント化する場合、パラメータや戻り値の説明を追加することが重要です。これにより、他の開発者が関数の使い方や返される値を理解し、効果的に使用できるようになります。
  3. 統一されたスタイルを使用する：ドキュメンテーションで使用する記法や文法のスタイルは、統一されたものを使用することが重要です。これにより、ドキュメンテーションの一貫性を保ち、読みやすく理解しやすいドキュメントを作成することができます。
  4. ドキュメンテーションを最新に保つ：コードの変更がある度に、ドキュメンテーションも更新するように心がけることが重要です。これにより、他の開発者が最新の情報を得ることができます。
  5. オーバードキュメントを避ける：不要な情報を含めたり、冗長な説明をしたりすることで、ドキュメントが読みにくくなります。必要な情報に絞って、簡潔に説明することが重要です。
  6. サンプルコードを提供する：コードのドキュメントには、使用例やサンプルコードを提供することが重要です。これにより、他の開発者がコードの使用方法を理解し、迅速に開発を進めることができます。

以上が、TSDocを使った効果的なドキュメンテーションのためのベストプラクティスです。これらを遵守することで、より読みやすく、明確なコードのドキュメントを作成することができます。

附録

編集

チートシート

編集

TSDocで使用される基本的なタグとその使い方の概要です。

TSDocのタグの分類とその機能
タグ 分類 説明
@abstract Class/Interface 抽象メンバーを示す
@async Function 非同期関数を示す
@class Class/Interface クラスを示す
@deprecated Class/Interface/Enum/Function/Method/Property 使われなくなったAPIを示す
@enum Enum 列挙型を示す
@function Function 関数を示す
@inheritDoc Class/Interface/Method/Property 親クラス、インターフェース、メソッド、またはプロパティからの継承ドキュメントを示す
@interface Interface インターフェースを示す
@param Function/Method/Constructor パラメータの説明を示す
@private Class/Interface/Enum/Function/Method/Property プライベートメンバーを示す
@property Class/Interface プロパティを示す
@protected Class/Interface/Enum/Function/Method/Property プロテクトメンバーを示す
@public Class/Interface/Enum/Function/Method/Property パブリックメンバーを示す
@readonly Class/Interface/Property 読み取り専用プロパティを示す
@returns Function/Method 戻り値の説明を示す
@template Function/Class/Interface テンプレートの説明を示す
@this Function/Method/Constructor this キーワードの説明を示す
@throws Function/Method 例外の説明を示す
@type Function/Method/Constructor/Property 値の型を示す
@typedef Type Alias 型のエイリアスを示す
@virtual Method 仮想メソッドを示す
@inheritdoc Class/Interface/Method/Property 継承元からのドキュメントを継承することを示す
@example Class/Interface/Function/Method コードの例を示す
@remarks Class/Interface/Enum/Function/Method/Property 補足説明を示す
@see Class/Interface/Enum/Function/Method/Property 関連するドキュメントを示す
@since Class/Interface/Enum/Function/Method/Property APIが導入されたバージョンを示す
@summary Class/Interface/Enum/Function/Method/Property 要約を示す
@todo Class/Interface/Enum/Function/Method/Property 未完了のタスクを示す

これらのタグは、/** ... */ブロックコメントの中に記述します。例えば、次のような関数をドキュメント化する場合、以下のようにTSDocコメントを追加します。

以下は、TSDocの主要なタグを使用したTypeScriptのコード例です。 

/**
 * Represents a point in 2D space.
 * @public
 */
class Point {
  /**
   * The x-coordinate of the point.
   */
  x: number;
  /**
   * The y-coordinate of the point.
   */
  y: number;

  /**
   * Creates a new point.
   * @param x - The x-coordinate of the point.
   * @param y - The y-coordinate of the point.
   */
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }

  /**
   * Returns the distance between this point and another point.
   * @param other - The other point.
   * @returns The distance between the two points.
   */
  distanceTo(other: Point): number {
    const dx = this.x - other.x;
    const dy = this.y - other.y;
    return Math.sqrt(dx * dx + dy * dy);
  }
}

/**
 * A collection of points.
 * @public
 */
class PointCollection {
  /**
   * The points in the collection.
   */
  private points: Point[];

  /**
   * Creates a new point collection.
   * @param points - An array of points to initialize the collection with.
   */
  constructor(points: Point[]) {
    this.points = points;
  }

  /**
   * Adds a point to the collection.
   * @param point - The point to add.
   */
  add(point: Point): void {
    this.points.push(point);
  }

  /**
   * Returns the closest point to a specified point.
   * @param target - The point to find the closest point to.
   * @returns The closest point in the collection.
   */
  findClosest(target: Point): Point {
    let closest: Point | undefined;
    let closestDistance = Infinity;
    for (const point of this.points) {
      const distance = point.distanceTo(target);
      if (distance < closestDistance) {
        closest = point;
        closestDistance = distance;
      }
    }
    if (!closest) {
      throw new Error('No points in collection');
    }
    return closest;
  }
}

このTypeScriptのコードは、2D空間の点を表すPointクラスと、その点のコレクションを表すPointCollectionクラスを定義しています。

Pointクラスには、x座標とy座標のプロパティがあり、distanceToメソッドを使用して他の点との距離を計算することができます。このクラスは、@publicタグで公開されており、他のモジュールから使用することができます。

PointCollectionクラスは、Pointオブジェクトの配列を引数として取り、配列内のすべての点を格納します。このクラスも、@publicタグで公開されています。

PointCollectionクラスには、addメソッドがあり、新しいPointオブジェクトを追加できます。また、findClosestメソッドを使用して、指定された点に最も近い点を検索することができます。このメソッドは、Pointオブジェクトを返します。

このコードには、TSDocの主要なタグが使用されています。クラス、メソッド、およびプロパティには、@class、@public、@param、および@returnsタグが含まれます。これらのタグは、コードのドキュメンテーションに必要な情報を提供します。

用語集

編集
  1. ドキュメンテーションコメント（documentation comment）：TSDocで書かれたドキュメントのコメント。JavaScriptやTypeScriptのコード内に記述されます。
  2. JSDocコメント（JSDoc comment）：TSDocの前身であるJSDocで書かれたドキュメントのコメント。現在は互換性のためにTSDocでも使用可能です。
  3. タグ（tag）：TSDocで使用される、特定の情報を表すマークアップ要素。@で始まり、名前とオプションの説明を持ちます。
  4. ブロックタグ（block tag）：タグのうち、説明文を持つブロック要素を表すタグのこと。例：@param、@returns。
  5. インラインタグ（inline tag）：タグのうち、説明文の一部として使用されるインライン要素を表すタグのこと。例：@link、@code。
  6. オプション（option）：タグに含まれる、追加の情報を提供するための要素。例：@paramのtypeオプション。
  7. ディレクティブ（directive）：ドキュメンテーションコメント内で使用される、TSDoc以外のツールに指示を与えるための命令。例：@ts-ignore。
  8. ドキュメンテーションセット（documentation set）：プログラムのすべてのドキュメントコメントの集合。TSDocを使用して自動的に生成することができます。
  9. ドキュメンテーションページ（documentation page）：ドキュメンテーションセットの一部を表示する単一のページ。一般的に、特定の関数やクラスに対応します。
  10. ドキュメンテーションツール（documentation tool）：TSDocによって生成されたドキュメントを表示するためのツール。例：TypeDoc、ESDoc。
"https://ja.wikibooks.org/w/index.php?title=TSDoc&oldid=234943" より作成