「どんなシステムを作るのか」をJavadocで表現する

前回のおさらい「Javadocの基本」

Javadocの機能は、ソースコード中の「/**」と「*/」で囲まれたドキュメンテーションコメントから、リファレンスドキュメントを生成することでした。ソースコードとドキュメンテーションコメントが一体になっているため、開発者は設計を考えながらソースコードを書き、その設計内容をドキュメ ンテーションコメントとして残すといった一連の流れをソースコード上で行うことができます。

Javadocは、標準クラスライブラリのリファレンスドキュメントを見れば、クラスやメソッドの使い方を理解するのにとても役に立つことはわかります。しかし、システム開発現場のドキュメントとしては、それだけでは不十分です。

Javadocに足りないのは「ソースコードが正しいか」ということを表現できないことです。正しさを確認するには2つの視点があります。1つは 「どんなシステムを作るのか」という視点。もう1つは「どのように検証するのか」という視点です。これらの視点は、Javadocを拡張すれば補うことが できます。

今回の内容

今回は「どんなシステムを作るのか」を表現するための方法を考えてみます。

はじめに、Javadocの拡張の仕方を検討し、実装方法を紹介します。次に、Antを利用してビルドプロセスにJavadocの拡張を組み込みます。

「どんなシステムを作るのか」を表現する

どんなシステムを作るのかは、様々な要件の検討を経て仕様書に反映されています。リファレンスドキュメントから基となった仕様書ファイルへのリンクがあれば、リンク先の仕様を理解してソースコードが妥当な作りになっているのか確認することができます。

このような任意のファイルにリンクを作るタグは標準のjavadocタグにありません。そこで、この機能を実現するカスタムタグを作ってみます。

今回の連載では、このカスタムタグを「仕様書タグ」と呼ぶことにします。

仕様書タグを作成する

今回作成する仕様書タグは3種類あります。

以下は仕様書タグを使って、リファレンスドキュメントを作成したソースコードの完成イメージです。

図1：生成されたリファレンスドキュメント
（画像をクリックすると別ウィンドウに拡大図を表示します）

@specタグが生成したリンクは、後述する仕様書ファイルを置く規定ディレクトリの「text.xls」を指しています。残りのタグは、文字列を生成します。

今回使用するソースコードのサンプルは以下のURLからダウンロードできます。