 |
|
| Javadocから考える開発ドキュメンテーション |
第２回：「どんなシステムを作るのか」をJavadocで表現する
著者：ウルシステムズ 足立 祐一 2007/8/24
|
|
|
| 前のページ 1 2 3
|
|
| Antで作業を自動化する
|
コマンド実行例をみてわかるように、利用するカスタムタグが増えると入力するコマンドも長くなってきます。これではテストが大変なので、Antのタスクにしてしまいましょう。
Antでは、デフォルトでJavadocを利用するタスクが定義されているため、これを使います。その後javadocタスクをビルドプロセスに組み込んで、コンパイルやJarファイルへのパッケージングと連動してリファレンスドキュメントが生成されるようにします。
今回の連載ではAntについては詳しく言及しません。Antの詳細は以下のURLを参照してください。
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によって解決できるシステムを提供すべく、日々奮闘中。
|
|
|
|
|
|
