JsDoc Toolkitを使う!

JsDoc Toolkit Ant Task

最終更新:

aias-jsdoctoolkit

- view
管理者のみ編集可

トップページ > ドキュメントの作成 >

JsDoc Toolkit Ant Task

JsDoc Toolkit Ant TaskはJsDoc ToolkitをAntタスクとして実行するラッパープログラムです。JsDoc Toolkitのコマンドラインオプションのほとんどを使用でき、かつAntビルドファイル内で簡単にJsDoc Toolkitを利用できます。

準備

インストール

下記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 へのクラスパスを必ず設定してください。

< taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"
          classpath="/path/to/jsdoctoolkit-ant-task-1.0.jar;/path/to/js.jar" />

その後、タスクをコールします。コマンドラインオプションは属性として指定します。詳細はこちらを参照してください。

< jsdoctoolkit jsdochome="/path/to/jsdoc_toolkit/" template="jsdoc"
          outputdir="/output/dir/" inputdir="/dir/of/javascript/files/" />

入力ファイルの指定には、 <fileset> 要素か、 <source> 要素をネストさせることもできます。 <source> 要素は独自要素で、 file 属性に1ファイルまたはディレクトリのパスを指定します。

< jsdoctoolkit jsdochome="/path/to/jsdoc_toolkit/" template="jsdoc" outputdir="/output/dir/" >
     < source file="/a/js/soucefile.js" />
     < source file="/another/js/soucefile.js" />
</ jsdoctoolkit>

ユーザ定義のパラメータ(-Dオプションに相当)は、独自要素の <arg> 要素を使って渡します。 name 属性と value 属性にそれぞれパラメータ名と値を指定します。

< jsdoctoolkit jsdochome="/path/to/jsdoc_toolkit/" template="jsdoc"
          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> 要素の設定が出力に反映されない現象があったため、ソースコードを修正し再ビルドを行いました。似た現象が発生した方は参考にしてください。

  1. 下記リポジトリからソースコードをチェックアウトします。
    http://jsdoc-toolkit-ant-task.googlecode.com/svn/trunk/
  2. JsDocToolkit.javaの181行目を以下のように変更します。

    cmdVector.add("-D=" + args.elementAt(i).getName() + ":" + args.elementAt(i).getValue());

  3. ソースに含まれるbuild.xmlを実行し、再ビルドを行います。(おそらくテストパス設定の関係で)ビルドファイルの実行は途中で失敗しますが、新しいjsdoctoolkit.jarが生成されているはずです。    

   

目安箱バナー