TypeDoc入門

TypeScript用ドキュメントツール
http://typedoc.org/

TypeDocを選ぶ理由

1. 無駄なコメントを書く必要がない
   • 型情報とか
2. TypeScriptの文法にちゃんと対応してる
   • ver. 1.4.1の範囲（2015-06-25現在）
3. デフォルトで奇麗で便利な出力
   • 検索機能付き
4. 型定義ファイル(*.d.ts)からも出力可能

インストール

npm経由で。

npm i typedoc -g

使い方

nodejsのコマンドラインツールとして提供されているのでコマンドラインからが基本になる。

コマンドラインで

基本

typedoc --out OUTDIR SRCDIR

裏でTypeScriptのコンパイラが動くので、tscへのコマンドラインオプションをビルド時と同様に設定する必要がある。

tscのオプションも必要

typedoc --out OUTDIR SRCDIR -m "commonjs" -t "ES6"

タスクランナーと組み合わせて

gulpとGruntのプラグインが公開されている。

• gulp-typedoc
• grunt-typedoc

コメントの書き方

JavaDoc形式。YUIDoc形式のように、型情報を{String}のような表記で書く必要は無く.tsのソースを解析して出してくれる。

整形して解析してくれるタグは@paramと@return(s)の２つだけ。ただしそれ以外のタグを書いてあってもそれっぽく表示してくれるので問題ない。

コメント中にはHTMLやMarkdown形式が使える。

/**
* 関数の説明
* @param arg 引数の説明文だけでOK
*/
function doSomething<T,S>(arg:T):S{
    //...
}

各種コマンドラインオプション

公式サイトで説明されていないものも結構ある。

型定義ファイルをドキュメント化する

--includeDeclarationsオプションをつける。

型定義ファイルしか提供されてない場合でもそこからドキュメント化できる。下手に作られたドキュメントより見やすい。

ファイルでまとめるかモジュールでまとめるか

--modeオプションにfile / modules と設定する事でドキュメントのディレクトリ構造をファイルでまとめるかモジュールでまとめるか決められる。

実際に設定を変えてみて好きな方を設定すると良いと思われる。

ソースの解析結果をJSON形式で出力する

--jsonオプション。
--json <outputfilename.json>とすることでJSON形式で解析結果を出力できる。コレを使って色々改変してみるのも面白いかもしれない。

ドキュメントの名前を設定する

--nameオプション。

Google Analyticsと連携する

--gaID と --gaSite

ドキュメントの見た目（テーマ）を変える

--themeオプション。デフォルトではdefaultとminimalが用意されている。デフォルトの出来がいいのであまり使わないかも？

画像とかをつかいたい

--mediaオプションでディレクトリを指定する。

謎オプション

• --verbose
  • ver.0.3.4 だと無効？
• --logger
  • none/consoleを指定。ロガーを指定するらしいが何のためかは不明
• --option
  • typedoc.jsというjsにオプションを書いておくと勝手に読み込んでくれるらしいのだが、書き方が分からないので試せなかった
• --plugin
  • 読み込むべきnpmプラグインを指定する、とあるが何のためにあるのか不明

TS1.5のソースをドキュメント化したい

現時点(2015-06-26)ではTypeDocはTS1.5に対応していない。

1. 方法１：
   • tsソースを一旦型定義ファイル(d.ts)に変更する
   • 1.5のtscでtsファイルからd.tsを生成
   • typedocでそのd.tsをソースとして生成
2. 方法２：
   • (未確認)typedoc内部のtypesciptを置き換える
   • https://github.com/sebastian-lenz/typedoc/issues/95#issuecomment-101915453