JsDoc Toolkitを使う!
JsDoc Toolkit Ant Task
最終更新:
aias-jsdoctoolkit
JsDoc Toolkit Ant Task
JsDoc Toolkit Ant TaskはJsDoc ToolkitをAntタスクとして実行するラッパープログラムです。JsDoc Toolkitのコマンドラインオプションのほとんどを使用でき、かつAntビルドファイル内で簡単にJsDoc Toolkitを利用できます。
- このページはhttp://code.google.com/p/jsdoc-toolkit-ant-task/を元に作成しました。
- ここではAntそのものの説明は行いません。公式サイトやWeb上の情報を参照してください。
準備
インストール
下記URLから jsdoctoolkit-ant-task-1.0.jar をダウンロードし、適当なディレクトリに配置してください。
動作環境
JsDoc Toolkit Ant Taskの動作には、JsDoc Toolkit本体がインストールされた環境が必要です。
例
Antビルドファイル内でJsDoc Toolkit Ant Taskを使用する手順を説明します。
まず、
jsdoctoolkit
タスクを定義します。ダウンロードした
jsdoctoolkit-ant-task-1.0.jar
とRhino -
js.jar
へのクラスパスを必ず設定してください。
classpath="/path/to/jsdoctoolkit-ant-task-1.0.jar;/path/to/js.jar" />
その後、タスクをコールします。コマンドラインオプションは属性として指定します。詳細はこちらを参照してください。
outputdir="/output/dir/" inputdir="/dir/of/javascript/files/" />
入力ファイルの指定には、 <fileset> 要素か、 <source> 要素をネストさせることもできます。 <source> 要素は独自要素で、 file 属性に1ファイルまたはディレクトリのパスを指定します。
< source file="/a/js/soucefile.js" />
< source file="/another/js/soucefile.js" />
</ jsdoctoolkit>
ユーザ定義のパラメータ(-Dオプションに相当)は、独自要素の <arg> 要素を使って渡します。 name 属性と value 属性にそれぞれパラメータ名と値を指定します。
outputdir="/output/dir/" inputdir="/dir/of/javascript/files/" >
< arg name="argOne" value="foo" />
< arg name="argTwo" value="bar" />
</ jsdoctoolkit>
サンプル ビルドファイル
管理人が作成したビルドファイルのサンプルをこちらからダウンロードできます。使用する場合はパスや属性を各自の環境に合わせてください。
属性一覧
属性名 | 説明 | 必須 |
jsdochome | JsDoc Toolkitのインストールディレクトリ。注意:末尾に"/"が必要です。 | yes |
template | 使用するテンプレート名。 -t オプションに相当します。JsDoc Toolkit Ant Taskではテンプレートは"templates/"ディレクトリ直下に存在すると仮定されています。 | yes |
outputdir | 作成されたドキュメントの出力ディレクトリ。 -d オプションに相当します。注意:末尾に"/"が必要です。 | yes |
inputdir | JavaScript(やその他)の入力ファイルを含むディレクトリ | <source> 要素がネストされていなければyes |
encoding | 入出力ファイルの文字エンコーディング。 -e オプションに相当します。 | no, デフォルトはutf-8 |
depth | 入力ディレクトリからファイルをたどる階層数。 -r オプションに相当します。 | no, デフォルトは10。ただし <inputdir> 属性が指定されていないなら無効。 |
includeundocumented | trueの場合、ドックコメントのないコードも出力します。 -a オプションに相当します。 | no, デフォルトはfalse |
includeunderscored |
trueの場合、"_"から始まるメンバをprivateと見なしません。
-A
オプションに相当します。 ※JsDoc Toolkit 2.1.0では-Aオプションは廃止されており、この属性も無効です。 |
no, デフォルトはfalse |
includeprivate | trueの場合、privateなメンバもドキュメントに出力します。 -p オプションに相当します。 | no, デフォルトはfalse |
verbose | 処理内容について詳細なメッセージを出力します。 -v オプションに相当します。 | no, デフォルトはfalse |
extensions | 入力ファイルの拡張子をカンマ区切りで指定します。 -x オプションに相当します。 | no, デフォルトはjs |
log | 指定されたファイルにログを出力します。 -o オプションに相当します。 | no |
config | コンフィグファイルのパスを指定します。 -c オプションに相当します。 | no, このオプションが指定された場合、他のオプションは全て無視されます。 |
付記:<arg>要素のバグ?について
管理人の環境では <arg> 要素の設定が出力に反映されない現象があったため、ソースコードを修正し再ビルドを行いました。似た現象が発生した方は参考にしてください。
-
下記リポジトリからソースコードをチェックアウトします。
http://jsdoc-toolkit-ant-task.googlecode.com/svn/trunk/ -
JsDocToolkit.javaの181行目を以下のように変更します。
cmdVector.add("-D=" + args.elementAt(i).getName() + ":" + args.elementAt(i).getValue());
- ソースに含まれるbuild.xmlを実行し、再ビルドを行います。(おそらくテストパス設定の関係で)ビルドファイルの実行は途中で失敗しますが、新しいjsdoctoolkit.jarが生成されているはずです。