TypeScriptのドキュメント生成ツールに、
TypeDocがあります。コードの型情報から基礎的な情報を収集し、規格化が進んでいる
TSDocのアノテーションに対応しています。
コードコメントにはMarkdownによる装飾を利用できます。アノテーション用タグリストは
リファレンスを参照してください。たとえば、@paramや@returnで引数・戻り値にコメントを付けられます。型はTypescriptの型を参照するため記載不要、説明文を書きます。
JavaScript向けには従来からJSDocが使われていますが、JSDocはTypeScriptには標準対応しておらず、プラグインを追加する必要があります。
インストール
typedocコマンドが動作するよう、--globalまたは--save-devでインストールします。
$ npm install --save-dev typedoc
ドキュメント生成
typedocにはいくつかのオプション指定が必要です。オプションはコマンドラインまたは設定ファイルで指定できますが、以下のようにtypedoc.jsonファイルをプロジェクトルートに置くと毎回同じ挙動になります。
{
"entryPoints": ["./src/index.ts"],
"out": "doc",
"excludeExternals": true,
"exclude": "test/*",
"tsconfig": "tsconfig.json"
}
カレントディレクトリのtypedoc.jsonはデフォルトで読み込まれるため、単にtypedocコマンドを実行するだけでドキュメント生成できます。
対象ソースはentryPointsオプションで指定します。exportしたものだけがドキュメント対象になるため、内部コンポーネントなどはexportしているファイルをentryPointsに指定しておく必要があります。ディレクトリを指定した場合にはディレクトリ内のファイルが一括で対象になります。
指定可能なオプションのリストは、
公式ドキュメントを参照してください。
たとえば、クラスのprivateメソッドもデフォルトでドキュメント対象に含みますが、configで制御可能です。プロジェクトの目的に合わせて設定します。
typedocは、プロジェクトがclassベースで構成されていることを仮定しており、Reactの関数コンポーネントはexportした関数のみドキュメントに収録されます。サブコンポーネントがdocに掲載されない場合はexportを確認します。
typedocと連動してコンパイラが動作します。型定義に不備がある場合などにはエラーになり、その場合ドキュメント生成せず中断します。
依存関係が解決せずにエラーになる場合、npm installであらかじめライブラリをセットアップしておく必要があります。
デプロイ
生成されたドキュメントは、スタティックサイト向けのHTMLファイル群になります。必要に応じてウェブサーバーで配信します。
TypeDocの出力はレスポンシブ表示に対応しており、スマートフォンを含め幅広い環境で見易いドキュメントを生成できます。
