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

開発環境の例

カスタムタグを作るための環境として、OSおよびJDKのバージョンを以下のように想定して進めます。異なる場合は適宜読み替えてください。

OS	Microsoft Windows XP SP2
JDK	Java SE 6

表2：カスタムタグを作るための環境

なおJava SE 6は以下のURLからダウンロードできます。

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

JDKはcドライブ直下の「c:\java」にインストールし、今回のカスタムタグ作成プロジェクト「c:\projects \CustomTagletProject」をルートディレクトリとして作成することにします。プロジェクトのディレクトリ構成は以下の通りとします。

spec	仕様書を置くディレクトリ
src	ソースコードを置くディレクトリ
classes	ソースコードをコンパイルしてできたクラスファイルを置くディレクトリ
javadoc	ソースコードを基に作成したリファレンスドキュメントを置くディレクトリ

表3：プロジェクトのディレクトリ構成

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

@specタグはcom.sun.tools.doclets.Tagletインターフェースを実装したSpecTagletクラスとして実装します。メインとなる4つのメソッドの概略は次の通りです。

getName()メソッド: タグ名（spec）を返す。
toString(Tag)メソッド: タグのテキスト引数を元に、リファレンスドキュメントに仕様書へのリンクをあらわす文字列を返す。
toString(Tag[])メソッド: 複数のタグのテキスト引数を元に、リファレンスドキュメントに仕様書へのリンクをあらわす文字列を返す。
isInlineTag()メソッド: ブロックタグとするのでfalseを返す。

表4：メインとなる4つのメソッド

これら4つのメソッド以外には、タグを有効とするドキュメンテーションコメントの位置（コンストラクタ、クラス、メソッドなど）を設定するためのinXX()メソッドがあります。

さらにタグレットを有効化するために、以下のstaticメソッドを定義する必要があります。

register(Map): 引数のMapに、key=タグ名、value=タグのインスタンスを追加するよう実装する。

表5：タグレットを有効化するためのメソッド

これ以外のメソッドや詳細は、Sunが提供している以下のドキュメントを参考にしてください。

Tagletの概要
http://java.sun.com/javase/ja/6/docs/ja/technotes/guides/javadoc/taglet/
overview.html

カスタムタグを利用してみる

コマンドプロンプトを起動して、プロジェクトルートディレクトリに移動します。カスタムタグを利用するには、javadocコマンドをオプション付きで実行する必要があります。必要なオプションは「-tagletオプション」と「-tagletpathオプション」です。

「-tagletオプション」は、Tagletインターフェースを実装したクラスの完全クラス名（今回は「jp.co.ulsystems.tools.taglets.SpecTaglet」が相当します）を指定します。

「-tagletpathオプション」は「-tagletオプション」で指定したクラスのクラスファイルがあるパスを指定します。

javadocコマンドにはカスタムタグに関する以外のオプションもあります。リファレンスドキュメント（HTMLファイル）の文字エンコーディングや出力先ディレクトリを指定する場合は、それぞれ「-docencodingオプション」と「-dオプション」で指定します。

以下はコマンドの実行例です。

（画像をクリックすると別ウィンドウに拡大図を表示します）

@specタグと同様にして、仕様項目を表示する「@spec.chapter」タグ、仕様番号を表示するカスタムタグ「@spec.id」を、それぞれSpecChapterTagletクラス、SpecIdTagletクラスで実装します。こちらも利用してみましょう。

利用する際は、先ほどと同様にコマンドプロンプトからjavadocコマンドを入力します。以下の実行例のように「-tagletオプション」で、利用するカスタムタグクラスの完全クラス名を指定することを忘れないようにしましょう。