Javadocから考える開発ドキュメンテーション第2回

Antで作業を自動化する

コマンド実行例をみてわかるように、利用するカスタムタグが増えると入力するコマンドも長くなってきます。これではテストが大変なので、Antのタスクにしてしまいましょう。

Antでは、デフォルトでJavadocを利用するタスクが定義されているため、これを使います。その後javadocタスクをビルドプロセスに組み込んで、コンパイルやJarファイルへのパッケージングと連動してリファレンスドキュメントが生成されるようにします。

今回の連載ではAntについては詳しく言及しません。Antの詳細は以下のURLを参照してください。

THE APACHE ANT PROJECT
http://ant.apache.org/
The Ja-Jakarta Project
http://www.jajakarta.org/ant/
※対象ページ閉鎖

Antのバージョンは1.7.0を使用し、ディレクトリ構成は以下とします。また、antコマンドのあるディレクトリを環境変数（PATH）に追加しておきます。

Antルートディレクトリ	C:\apache-ant
ビルドファイル（build.xml)	プロジェクトルートディレクトリ \build.xml
プロパティファイル	プロジェクトルートディレクトリ \build.properties
jarファイル格納ディレクトリ	プロジェクトルートディレクトリ \lib

表6：Antのディレクトリ構成

Antでjavadocタスクを使うときのビルドファイルとプロパティファイルは次のようになります。

以下はbuild.xmlの内容です。

（画像をクリックすると別ウィンドウに拡大図を表示します）

以下はbuild.propertiesの内容です。

  spec=spec

	  doc=javadoc

	  src=src

	  class=classes

	  dist=lib

javadocコマンドで指定していたオプションが「tagletエレメント」に対応しています。

コマンドプロンプトを起動してプロジェクトルートディレクトリに移動します。SpecTagletなどがコンパイルされた状態で、以下のように入力しjavadocターゲットを実行すると、リファレンスドキュメントが生成されます。

C:\projects\CustomTagletProject> ant javadoc

ビルドプロセスに組み込むことが重要

Javadocの特徴の1つとして、ソースコードからバイトコードをコンパイルするようにドキュメントが生成できる、というものがあります。しかし、この生成のタイミングがずれ、バイトコードとドキュメントの齟齬が発生しては意味がありません。

そこで、クラスファイル削除タスクからコンパイルタスク、javadocコマンドタスク、jarパッケージングタスクまでを連続で実行できるようなビルドファイルを作成しておくと、この齟齬の発生を防ぐことができます。

このようにビルドプロセスにjavadocタスクを組み込んでおくことで、ソースコードとバイトコード、リファレンスドキュメントを常に同期させることができます。Javadocを活かすためには、ドキュメント生成をビルドプロセスに組み込むことも重要です。

以下はbuild.xmlの内容です。



	

	  

	  

	    

	      

	    

	    

	  

	  

	    

	      

	      

	        

	      

	    

	  

	  

	    
	         basedir="${class}"

	         includes="**/taglets⁄**" />

	  

	  

	以下省略

今回は、カスタムタグ自身がプロジェクトに含まれていましたが、通常はこのようにして作られたカスタムタグを配布し、他のプロジェクトにも活用することになるでしょう。jarにパッケージングされたカスタムタグの利用例は、次回に解説します。

次回は

今回は、Javadocに欠けている2つの視点のうち「どんなシステムを作るのか」について、仕様書タグを作成して表現しました。

仕様書の構造はプロジェクトごとに様々なため、今回のサンプルのままでは適用できないケースもあるでしょう。本連載を参考にして、それぞれのプロジェクトに適したタグを定義してみてください。

次回は、もう1つの視点「どのように検証するのか」について紹介します。カスタムタグを使うことは変わりませんが、今回の実装の仕方だけでは実現できない部分があります。また、継続的な開発にフィットさせる方法も合わせて検討します。