More than 1 year has passed since last update.

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のプラグインが公開されている。


コメントの書き方

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

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

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


/**
* 関数の説明
* @param arg 引数の説明文だけでOK
*/

function doSomething<T,S>(arg:T):S{
//...
}

スクリーンショット 2015-06-26 0.50.01.png


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

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


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

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

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


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

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

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


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

--jsonオプション。

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


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

--nameオプション。


Google Analyticsと連携する

--gaID--gaSite


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

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


画像とかをつかいたい

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


謎オプション



  • --verbose


    • ver.0.3.4 だと無効?




  • --logger



    • none/consoleを指定。ロガーを指定するらしいが何のためかは不明




  • --option



    • typedoc.jsというjsにオプションを書いておくと勝手に読み込んでくれるらしいのだが、書き方が分からないので試せなかった




  • --plugin


    • 読み込むべきnpmプラグインを指定する、とあるが何のためにあるのか不明




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

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


  1. 方法1:


    • tsソースを一旦型定義ファイル(d.ts)に変更する

    • 1.5のtscでtsファイルからd.tsを生成

    • typedocでそのd.tsをソースとして生成



  2. 方法2: