JavaScript のコードからモダンなドキュメントをさくっと生成してくれる『JSDuck』の使い方 – 導入編

phiary に引っ越しました. 毎日プログラミングやWebに関する情報を発信しています! RSS 登録してたまに覗いたり, tweet やハテブして拡散してもらえると幸いです.

logo-sencha

Pocket

今回は, 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 で公開されています.

GitHub

また SenchaCon 2011 でライブコーディングした模様が vimeo で公開されています.

SenchaCon 2011: Documenting with JSDuck from Sencha on Vimeo.

1時間と長いですが時間のあるかたはぜひ見てみてください.

up

jsduck のインストール

jsduck は Ruby の gem 経由でインストールすることができます.

$[sudo] gem install jsduck

また windows の場合 binary が用意されているようなので, こちらからサクッとインストールできるかもです.

Link

インストールに成功していれば下記のコマンドでバージョンが表示されます

$jsduck --version

試しに下記のコマンドを実行してみてください.

$jsduck --builtin-classes --output docs

実行したディレクトリに docs というディレクトリが生成されているのがわかるかと思います. docs/index.html を開いてみてください.

JavaScript 標準オブジェクトのドキュメントが表示されます.

$open docs/index.html

up

jsduck の使い方

使い方はシンプルです.

jsduck というコマンドに, 見てほしい js コードが入ったパスや, 出力先, タイトルなどを指定して実行するだけです.

$jsduck ./src --output ./docs --title "tmlib.js docs",

上記のコマンドは src ディレクトリ内にある JavaScript コードを解析して “tmlib.js docs” というドキュメントを docs ディレクトリに出力してくれという意味になります.

簡単ですよね♪

まだまだ便利なオプションがたくさんあるのですが, それは次回の実践編で紹介します!!

up

jsduck デモ

jsduck を使ったデモを作りました. GitHub に置いています.

GitHub

Mac の場合は docs.sh, Windows の場合は docs.bat を実行してみてください.

src 内の JavaScript コードを解析して docs 内にドキュメントを生成してくれます.

src 内のコードやコメントをいじって色々生成して遊んでみてください.

up

TRACK BACK URL

POST COMMENT

メールアドレスが公開されることはありません。

COMMENT