はじめに
1年くらい前に、JsDoc ToolkitでJavascriptのドキュメントを自動生成 - 大人になったら肺呼吸というエントリで、JsDoc ToolkitというJavaScriptのドキュメントジェネレータについて書きました。その後、Jsdoc Toolkitがアップデートされ、メジャーバージョンが上がっていたので、再度試してみました。
このエントリでは、Jsdoc Toolkitのセットアップと簡単な使い方について書いています。
必要なソフトウェア
- Javaのランタイム
ちなみに、僕の環境は以下のようになっています。
java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b02) Java HotSpot(TM) Client VM (build 1.5.0_16-b02, mixed mode, sharing)
Jsdoc Toolkitのインストール
- Google Code Archive - Long-term storage for Google Code Project Hosting.にアクセスする。
- 画面右にあるFeatured Downloads:からモジュールをダウンロードする。(2008.3.30現在の最新版は、2.1.0)
- zip圧縮されているので、解凍ソフトを使用して解凍した後、適当なディレクトリに保存する。(今回は、D:ドライブ直下に保存する。)
Jsdoc Toolkitでドキュメントを自動生成する
1. JsDoc Toolkitのインストールディレクトリ配下に作業用ディレクトリ(work)を作成する。
ディレクトリの構成
D:. └─jsdoc-toolkit ├─app │ ├─frame │ ├─handlers │ │ └─XMLDOC │ ├─lib │ │ └─JSDOC │ ├─plugins │ ├─t │ └─test ├─conf ├─java │ ├─classes │ └─src ├─templates │ └─jsdoc │ └─static └─work
2. ドキュメント生成対象となるjsファイルを用意し、workディレクトリ配下にコピーする。(sample.js)
sample.js(UTF-8)
/** @fileOverview 概要 @name samle.js @author hoge hoge@mail.jp @version 1.0 */ /** @param {String} 名前 @type Array */ function getPerson(name) { }
3. 以下のコマンドを実行し、ドキュメントを自動生成する。
java -jar jsrun.jar app/run.js -t=templates/jsdoc work/sample.js
4. outディレクトリに、htmlファイルが生成されているので、ブラウザでindex.htmlを表示して確認することができる。
おわりに
JsDoc Toolkit1.xと2.xではディレクトリ構成が変わっていているので注意が必要です。メジャーバージョンが上がると、また変更されるかもしれないので、定期的にチェックする必要があります。