 |
|
| Javadocから考える開発ドキュメンテーション |
第２回：「どんなシステムを作るのか」をJavadocで表現する
著者：ウルシステムズ 足立 祐一 2007/8/24
|
|
|
| 前のページ 1 2 3 次のページ
|
|
| 開発環境の例
|
カスタムタグを作るための環境として、OSおよびJDKのバージョンを以下のように想定して進めます。異なる場合は適宜読み替えてください。
| OS |
Microsoft Windows XP SP2 |
| JDK |
Java SE 6 |
表2：カスタムタグを作るための環境
なおJava SE 6は以下のURLからダウンロードできます。
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が提供している以下のドキュメントを参考にしてください。
|
| カスタムタグを利用してみる
|
コマンドプロンプトを起動して、プロジェクトルートディレクトリに移動します。カスタムタグを利用するには、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オプション」で、利用するカスタムタグクラスの完全クラス名を指定することを忘れないようにしましょう。
（画像をクリックすると別ウィンドウに拡大図を表示します）
|
前のページ 1 2 3 次のページ
|
|
|
|
|
著者プロフィール
ウルシステムズ株式会社 足立 祐一
コンサルタント
Javaを中心にアーキテクチャ設計〜アプリケーション開発に従事し、製造業界、金融業界のSIerを経て現職。新しい技術、古い技術を駆使し、お客様の課題をITによって解決できるシステムを提供すべく、日々奮闘中。
|
|
|
|
|
|
