ドックレットの概要
目次
ドックレットの基本
ドックレットとは、Java™ プログラミング言語で記述したプログラムのうち、ドックレット API を使用して Javadoc ツールの内容と出力形式を指定したものです。Javadoc ツールのデフォルトでは、HTML 形式の API ドキュメントを生成するための、Sun™ が提供した「標準」ドックレットが使用されます。しかし、独自のドックレットを作成して Javadoc の出力を好みの形式にカスタマイズすることもできます。ドックレットは、ドックレット API を使用してゼロから作成することも、必要に応じて標準ドックレットに手を加える形で作成することもできます。ドックレットは、次の基本手順に従って作成し、使用します。
- ドックレットとなる Java プログラムを記述します。ドックレット API を使用するためには、com.sun.javadoc.* をインポートする必要があります。作成したプログラムのエントリポイントは、public static boolean start メソッドのあるクラスです。そのメソッドは、パラメータとして RootDoc を取ります。
- ドックレットをコンパイルします。コンパイルには、Java 2 SDK に含まれるコンパイラ javac を使用できます。
- -doclet startingclass オプションを指定して Javadoc ツールを実行し、作成したドックレットが指定する出力を生成します。ここで、startingclass は、手順 1 で説明した開始クラスの完全指定の名前です。
コマンド行オプション -doclet を指定せずに javadoc を実行した場合は、デフォルトで HTML 形式の API ドキュメントを生成する標準ドックレットが使用されます。
com.sun.javadoc パッケージは、ドックレット API を定義するいくつかのインタフェースで構成されています。これらのインタフェースは、Java 2 SDK の lib/tools.jar ファイルに含まれています。このファイルには、これらのインタフェースを実装するクラスが含まれる private パッケージも入っています。さらに、tools.jar ファイルには、標準ドックレットを実装したクラスも含まれています。
簡単なドックレットの例
次に、小さなクラスが 1 つだけ含まれる簡単なドックレットの例を示します。この例を見れば、ドックレットの仕組みについて感触をつかめるはずです。import com.sun.javadoc.*; public class ListClass { public static boolean start(RootDoc root) { ClassDoc[] classes = root.classes(); for (int i = 0; i < classes.length; ++i) { System.out.println(classes[i]); } return true; } }コードから推察できるように、このドックレットは、javadoc の処理対象となるクラスについて、その名前を標準出力に書き出します。
ドックレットに関して最初に注意するべき点は、ドックレット API を使用できるようにするために com.sun.javadoc パッケージをインポートしなければならないということです。エントリポイントは、どのドックレットの場合にも public static boolean start メソッドです。start メソッドは、パラメータとして RootDoc を取ります。このパラメータには、javadoc の実行時にコマンド行に指定されたオプションと、javadoc の処理対象となるクラスとパッケージについての情報が入っています。
RootDoc は、classes というメソッドを定義しています。このメソッドからは、javadoc が解析するクラスが要素として入っている ClassDoc 配列が返されます。次に、for ループで、ClassDoc 配列に含まれる各クラスの名前を出力します。ClassDoc を println に引き渡すと、ClassDoc が表しているクラスの名前が出力されます。
このドックレットを実行するには、まずコンパイルする必要があります。コンパイルは、javac コンパイラで行います。ドックレット API のクラスファイルは Java 2 SDK の lib/tools.jar ファイルに含まれていますが、javac はこのクラスファイルを自動的にはロードしません。このため、次の例のようにして、コンパイラの classpath に tools.jar を含める必要があります。
javac -classpath C:\jdk1.3\lib\tools.jar ListClass.javaListClass ドックレットを実行するには、コンパイルしたドックレットを javadoc の -doclet および -docletpath タグで指定します。たとえば、このドックレットを MyClass.java というファイルに対して実行するには、次のコマンドを使用します (ListClass.class が現在のディレクトリ内にあると想定)。
% javadoc -doclet ListClass -docletpath . MyClass.java出力は、「MyClass」という文字列になります。このコマンドを使用するとき、tools.jar をクラスパス上に置く必要はありません。そのファイルは、Javadoc ツールが自動的にロードするからです。
コマンド行オプションについての注:javadoc -help を実行するとわかるように、Javadoc ツールにはコマンド行オプションが 2 セットあります。一方のセットは汎用で、どのドックレットでも使用できます。もう一方のオプションのセットは、標準ドックレット専用です。この 2 番目のオプションのセットは、カスタムドックレットを使う場合には利用できません。カスタムドックレットでは、ドックレット独自のコマンド行オプションを定義することもできます。このあとの例を参照してください。
API ドキュメントを生成するには、ドックレットは、この簡単な例よりもかなり複雑になります。javadoc で生成する API ドキュメントの形式をカスタマイズする場合は、ドックレットを自分でゼロから作成するよりも、デフォルトの標準ドックレットに修正を加える形で作成した方が簡単です。
例 - 標準ドックレットのサブクラス化
Javadoc ツールの出力をカスタマイズするには、必要な出力の内容と形式を指定する独自のドックレットを作成する必要があります。デフォルトの出力とほぼ同じ形式の HTML 出力が必要な場合は、ドックレット作成の出発点として、標準ドックレットを利用すると便利です。標準ドックレットに含まれる適切なクラスをサブクラス化し、必要な出力が生成されるようにメソッドを追加またはオーバーライドします。あるいは、標準ドックレット全体をコピーして、それに修正を加えていくという方法もあります。標準ドックレットのコピーを出発点として使用する場合は、必要に応じて、各ソースファイルの先頭にある package 文を削除し、新しい独自のパッケージ名に置き換えてください。実例は、「How can I modify the standard doclet to produce links to source code from the API documentation?」を参照してください。
例 - カスタムタグの作成と処理
ドキュメンテーションコメントの中で、@param や @return などの標準タグに加えて、カスタムタグ (@mytag) を使用する場合について考えてみます。カスタムタグの中の情報を使用するには、そのカスタムタグを表す Tag のインスタンスをドックレットで使用する必要があります。このためのもっとも簡単な方法の 1 つは、Doc または Doc のサブクラスの tags(String) メソッドを使用することです。このメソッドは、名前が String 引数に一致するすべてのタグを含む Tag オブジェクトの配列を返します。たとえば、method が MethodDoc のインスタンスである場合、コードは次のようになります。
method.tags("mytag")
このコードは、メソッドのドキュメンテーションコメントに含まれるすべての @mytag を表す Tag オブジェクトの配列を返します。@mytag タグ内の情報へは、Tag の text メソッドを使用すればアクセスできます。このメソッドは、タグの内容を表す文字列を返すので、用途に応じてこの文字列を解析したり使用したりできます。たとえば、ドキュメンテーションコメントに、次のようなカスタムタグが含まれているとします。
@mytag Some dummy text.この場合、text メソッドは、「Some dummy text.」という文字列を返します。
次に示すコードは、これまで説明した考え方を使用して、メソッドのコメント内に見つかるタグのうち、指定されたタグのすべてのインスタンスに関連付けられたテキストを表示するスタンドアロンドックレットです。これは標準ドックレットのサブクラスではありません。このドックレットは、すべてのコメントに含まれるそのタグのすべてのインスタンスを検出するように拡張することができます。
import com.sun.javadoc.*;
public class ListTags {
public static boolean start(RootDoc root){
String tagName = "mytag";
writeContents(root.classes(), tagName);
return true;
}
private static void writeContents(ClassDoc[] classes, String tagName) {
for (int i=0; i < classes.length; i++) {
boolean classNamePrinted = false;
MethodDoc[] methods = classes[i].methods();
for (int j=0; j < methods.length; j++) {
Tag[] tags = methods[j].tags(tagName);
if (tags.length > 0) {
if (!classNamePrinted) {
System.out.println("\n" + classes[i].name() + "\n");
classNamePrinted = true;
}
System.out.println(methods[j].name());
for (int k=0; k < tags.length; k++) {
System.out.println(" " + tags[k].name() + ": "
+ tags[k].text());
}
}
}
}
}
}
このドックレットが検索するタグは、変数 tagName によって指定されています。tagName には、カスタムタグでも標準タグでも、任意のタグの名前を指定できます。このドックレットは結果を標準出力に出力しますが、出力の形式は変更可能です。たとえば、HTML 形式の出力をファイルに書き出すことができます。
例 - カスタムコマンド行オプションの使用
カスタムのコマンド行オプションでドックレットを作成することもできます。ここでは、検索するタグの名前をコマンド行オプションで指定できるように、上記のドックレットを拡張します。カスタムオプションを使用するドックレットには、int 型の値を返す optionLength(String option) というメソッドが必要です。optionLength は、ドックレットが認識するカスタムオプションごとに、そのオプションを構成する要素 (トークン) の数を返さなければなりません。ここでは、-tag mytag という形式のカスタムオプションを使用できるようにしてみます。このカスタムオプションは -tag オプションそのものとその値という 2 つの要素で構成されるので、作成するドックレットの optionLength メソッドは、-tag オプションに対して 2 を返さなければなりません。また、optionsLength メソッドでは、認識できないオプションに対して 0 を返すようにします。
拡張を施したドックレットの完全なコードを次に示します。
import com.sun.javadoc.*;
public class ListTags {
public static boolean start(RootDoc root){
String tagName = readOptions(root.options());
writeContents(root.classes(), tagName);
return true;
}
private static void writeContents(ClassDoc[] classes, String tagName) {
for (int i=0; i < classes.length; i++) {
boolean classNamePrinted = false;
MethodDoc[] methods = classes[i].methods();
for (int j=0; j < methods.length; j++) {
Tag[] tags = methods[j].tags(tagName);
if (tags.length > 0) {
if (!classNamePrinted) {
System.out.println("\n" + classes[i].name() + "\n");
classNamePrinted = true;
}
System.out.println(methods[j].name());
for (int k=0; k < tags.length; k++) {
System.out.println(" " + tags[k].name() + ": " + tags[k].text());
}
}
}
}
}
private static String readOptions(String[][] options) {
String tagName = null;
for (int i = 0; i < options.length; i++) {
String[] opt = options[i];
if (opt[0].equals("-tag")) {
tagName = opt[1];
}
}
return tagName;
}
public static int optionLength(String option) {
if(option.equals("-tag")) {
return 2;
}
return 0;
}
public static boolean validOptions(String options[][],
DocErrorReporter reporter) {
boolean foundTagOption = false;
for (int i = 0; i < options.length; i++) {
String[] opt = options[i];
if (opt[0].equals("-tag")) {
if (foundTagOption) {
reporter.printError("Only one -tag option allowed.");
return false;
} else {
foundTagOption = true;
}
}
}
if (!foundTagOption) {
reporter.printError("Usage: javadoc -tag mytag -doclet ListTags ...");
}
return foundTagOption;
}
}
修正が加えられたこのドックレットでは、変数 tagName を、コマンド行オプション -tag で設定するようになっています。また、このカスタムオプションに対して 2 を返す optionLength メソッドが用意されています。なお、optionLength を明示的に呼び出す必要はありません。
さらに、このドックレットには、コマンド行オプションを解析して -tag オプションを探す readOptions メソッドも追加されています。このメソッドでは、オプションの情報が含まれた String 型の 2 次元配列を返す Rootdoc.options メソッドを利用しています。たとえば、次のコマンドを実行するとします。
javadoc -foo this that -bar other ...RootDoc.options メソッドは次の戻り値を返します。
options()[0][0] = "-foo" options()[0][1] = "this" options()[0][2] = "that" options()[1][0] = "-bar" options()[1][1] = "other"配列の 2 番目の添え字に入っている要素数は、optionLength メソッドにより判別されます。この例では、optionLength は -foo オプションに対して 3 を返し、-bar オプションに対して 2 を返します。
validOptions メソッドは、コマンド行タグの指定が正しいかどうかをチェックするための、省略可能なメソッドです。validOptions メソッドは、存在すれば自動的に呼び出されるため、明示的に呼び出す必要はありません。このメソッドでは、オプションの指定が正しい場合は true を返し、そうでない場合は false を返すようにします。また、指定の正しくないコマンド行オプションが見つかった場合に、validOptions から適切なエラーメッセージを表示することもできます。このドックレットの validOptions メソッドでは、-tag オプションが 1 つ指定されているかどうか、そして 2 つ以上指定されていないかどうかをチェックしています。