 |
|
| Javadocから考える開発ドキュメンテーション |
第２回：「どんなシステムを作るのか」をJavadocで表現する
著者：ウルシステムズ 足立 祐一 2007/8/24
|
|
|
| 1 2 3 次のページ
|
|
| 前回のおさらい「Javadocの基本」
|
Javadocの機能は、ソースコード中の「/**」と「*/」で囲まれたドキュメンテーションコメントから、リファレンスドキュメントを生成することでした。ソースコードとドキュメンテーションコメントが一体になっているため、開発者は設計を考えながらソースコードを書き、その設計内容をドキュメンテーションコメントとして残すといった一連の流れをソースコード上で行うことができます。
Javadocは、標準クラスライブラリのリファレンスドキュメントを見れば、クラスやメソッドの使い方を理解するのにとても役に立つことはわかります。しかし、システム開発現場のドキュメントとしては、それだけでは不十分です。
Javadocに足りないのは「ソースコードが正しいか」ということを表現できないことです。正しさを確認するには2つの視点があります。1つは「どんなシステムを作るのか」という視点。もう1つは「どのように検証するのか」という視点です。これらの視点は、Javadocを拡張すれば補うことができます。
|
| 今回の内容
|
今回は「どんなシステムを作るのか」を表現するための方法を考えてみます。
はじめに、Javadocの拡張の仕方を検討し、実装方法を紹介します。次に、Antを利用してビルドプロセスにJavadocの拡張を組み込みます。
|
| 「どんなシステムを作るのか」を表現する
|
どんなシステムを作るのかは、様々な要件の検討を経て仕様書に反映されています。リファレンスドキュメントから基となった仕様書ファイルへのリンクがあれば、リンク先の仕様を理解してソースコードが妥当な作りになっているのか確認することができます。
このような任意のファイルにリンクを作るタグは標準のjavadocタグにありません。そこで、この機能を実現するカスタムタグを作ってみます。
今回の連載では、このカスタムタグを「仕様書タグ」と呼ぶことにします。
|
| 仕様書タグを作成する
|
今回作成する仕様書タグは3種類あります。
- 仕様書そのもののファイルを指し示す「@specタグ」
- 仕様書中の項目を指し示す「@spec.chapterタグ」
- さらに細かい単位で規定された仕様を指し示す「@spec.idタグ」
表1：作成する仕様書タグ
以下は仕様書タグを使って、リファレンスドキュメントを作成したソースコードの完成イメージです。
/**
* カスタムタグを利用するメソッド。
*
* @spec test.xls
* @spec.chapter 2
* @spec.chapter 3
* @spec.id 100
* @spec.id 101
* @spec.id 102
* @spec.id 103
* @spec.id 104
*/
public void test() {}
図1：生成されたリファレンスドキュメント （画像をクリックすると別ウィンドウに拡大図を表示します）
@specタグが生成したリンクは、後述する仕様書ファイルを置く規定ディレクトリの「text.xls」を指しています。残りのタグは、文字列を生成します。
今回使用するソースコードのサンプルは以下のURLからダウンロードできます。
|
1 2 3 次のページ
|
|
|
|
|
著者プロフィール
ウルシステムズ株式会社 足立 祐一
コンサルタント
Javaを中心にアーキテクチャ設計〜アプリケーション開発に従事し、製造業界、金融業界のSIerを経て現職。新しい技術、古い技術を駆使し、お客様の課題をITによって解決できるシステムを提供すべく、日々奮闘中。
|
|
|
|
|
|
