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

テストタグを作成する

テストタグでリンクを付けるテストクラスとテストメソッドの命名規則を次のように決めます。

テストクラス名は、テストする対象のクラス名の前に「Test」をつけた名前とします。テストメソッド名はテスト対象のメソッド名の1文字目を大文字にし、直前に「test」をつけた名前とします。

例えば、テストする対象のクラスが「Sample」クラスだとすると、テストクラスは「TestSample」クラスになります。また、テストする対象のメソッドが「getSomething」メソッドだとすると、テストメソッドは「testGetSomething」メソッドになります。

さらにテストメソッドには、名称の後にさらに文字列を加えてもよいこととします。つまり「GetSomething」メソッドの場合、「testGetSomethingRed」メソッドもテストメソッドになります。

テストタグを使ってリファレンスドキュメントを作成したイメージは、次のようになります。

⁄**

	* @test

	*/

	public class Sample {

	    ⁄**

	     * カスタムタグを利用するメソッド。

	     * @spec test.xls

	     * @spec.chapter 2

	     * @spec.chapter 3

	     * @spec.id 100

	     * @spec.id 101

	     * @spec.id 102

	     * @spec.id 103

	     * @spec.id 104

	     * @test

	     */

	    public void getSomething() {}

	}

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

開発環境

「第2回：『どんなシステムを作るのか』をJavadocで表現する」と同様、カスタムタグを作るための環境を以下のように想定して進めます。異なる場合は適宜読み替えてください。

OS	Microsoft Windows XP SP2
JDK	Java SE 6

表2：開発環境

なお、Java SE 6については下記のURLよりダウンロードできます。

Java SE 6
http://java.sun.com/javase/ja/6/download.html

JDKはCドライブ直下の"C:\java"にインストールしておきます。

今回のテストタグ作成プロジェクトのルートディレクトリは「C:\projects\LinkTestTagletProject」とします。また、今回のプロジェクトでは、前回作成した仕様書タグのjarパッケージをあわせて利用します。

spec	仕様書を置くディレクトリ
src	ソースコードを置くディレクトリ
test	テストコードを置くディレクトリ
lib	利用するjarパッケージを置くディレクトリ
classes	ソースコードをコンパイルしてできたクラスファイルを置くディレクトリ
javadoc	ソースコードを元に作成したリファレンスドキュメントを置くディレクトリ

表3：ディレクトリ構成

カスタムタグに必要なメソッド

テストタグは「TestTaglet」クラスとして実装します。このクラスは、前回と同様に「com.sun.tools.doclets.Taglet」インターフェースを実装します。実装のメインとなる「toString(Tag)」メソッドがテストタグの書かれた位置を判断し、テストクラスやテストメソッドへのリンク文字列を返します。