今回は, JavaScript のコードから洒落乙なドキュメントをサクッと生成してくれる 『JSDuck』について紹介します.
コード中のコメントやコードを解析して 見やすくて使いやすいドキュメントを生成してくれます.
実は私が開発しているJavaScriptライブラリ『tmlib.js』のドキュメントも JSDock を使って生成していたりします.Docs
とてもオススメなので良かったら使ってみてください.
Table of contents
jsduck とは？
jsduck とは Sencha JavaScript フレームワークのために作られた API ドキュメント生成ツールです.
Sencha JavaScript のために作られたといっても, 普通の JavaScript コードでもちゃんと解析してドキュメントを生成してくれます.
JavaScript のドキュメント生成ツールとしては JsDoc Toolkit が有名だと思います. ただ, これは色々とイケてません(融通が効かなかったり, 検索イケてなかったり, デザインダサかったり, etc…)
その点 jsduck は sencha というプロダクトのために作られたツールというだけあって 非常に使いやすく見た目もイケています.
markdown に対応しているので, コメント中に markdown を書くことで 関連画像を貼り付けたり, デモへのリンクやサンプルコードを簡単にドキュメントに埋め込むことができます.
コードは GitHub で公開されています.
また SenchaCon 2011 でライブコーディングした模様が vimeo で公開されています.
SenchaCon 2011: Documenting with JSDuck from Sencha on Vimeo.
1時間と長いですが時間のあるかたはぜひ見てみてください.
jsduck のインストール
jsduck は Ruby の gem 経由でインストールすることができます.
$[sudo] gem install jsduck
また windows の場合 binary が用意されているようなので, こちらからサクッとインストールできるかもです.
インストールに成功していれば下記のコマンドでバージョンが表示されます
$jsduck --version
試しに下記のコマンドを実行してみてください.
$jsduck --builtin-classes --output docs
実行したディレクトリに docs というディレクトリが生成されているのがわかるかと思います. docs/index.html を開いてみてください.
JavaScript 標準オブジェクトのドキュメントが表示されます.
$open docs/index.html
jsduck の使い方
使い方はシンプルです.
jsduck というコマンドに, 見てほしい js コードが入ったパスや, 出力先, タイトルなどを指定して実行するだけです.
$jsduck ./src --output ./docs --title "tmlib.js docs",
上記のコマンドは src ディレクトリ内にある JavaScript コードを解析して “tmlib.js docs” というドキュメントを docs ディレクトリに出力してくれという意味になります.
簡単ですよね♪
まだまだ便利なオプションがたくさんあるのですが, それは次回の実践編で紹介します!!
jsduck デモ
jsduck を使ったデモを作りました. GitHub に置いています.
Mac の場合は docs.sh, Windows の場合は docs.bat を実行してみてください.
src 内の JavaScript コードを解析して docs 内にドキュメントを生成してくれます.
src 内のコードやコメントをいじって色々生成して遊んでみてください.