[Think IT] 第2回：「どんなシステムを作るのか」をJavadocで表現する (3/3)

TOP＞システム開発＞ Antで作業を自動化する

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

第２回：「どんなシステムを作るのか」をJavadocで表現する
著者：ウルシステムズ足立祐一 2007/8/24

前のページ 1 2 3

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の内容です。


		<?xml version="1.0" encoding="UTF-8"?>

		<project name="customTaglet" default="javadoc" basedir=".">

		  <property file="build.properties"/>

		  <target name="clean">

		    <delete>

		      <fileset dir="${class}" includes="**⁄*.class" />

		    </delete>

		    <delete file="${dist}/customtaglet.jar" />

		  </target>

		  <target name="compile" depends="clean">

		    <javac destdir="${class}">

		      <src path="${src}" />

		      <classpath>

		        <pathelement path="${java.class.path}" />

		      </classpath>

		    </javac>

		  </target>

		  <target name="compress" depends="compile">

		    <jar jarfile="${dist}/customtaglet.jar"

		         basedir="${class}"

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

		  </target>

		  <target name="javadoc" depends="compress">

		以下省略

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

次回は

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

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

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

前のページ 1 2 3

著者プロフィール
ウルシステムズ株式会社足立祐一
コンサルタント
Javaを中心にアーキテクチャ設計〜アプリケーション開発に従事し、製造業界、金融業界のSIerを経て現職。新しい技術、古い技術を駆使し、お客様の課題をITによって解決できるシステムを提供すべく、日々奮闘中。

INDEX
第2回：「どんなシステムを作るのか」をJavadocで表現する
	前回のおさらい「Javadocの基本」
	開発環境の例
	Antで作業を自動化する