|
|
ドックレットの概要 |
ドックレットは、次の基本手順に従って作成し、使用します。
コマンド行オプション -doclet を指定せずに javadoc を実行した場合は、HTML 形式の API ドキュメントを生成する標準ドックレットが使用されます。
com.sun.javadoc パッケージは、ドックレット API を定義するいくつかのインタフェースで構成されています。これらのインタフェースは、Java 2 SDK の lib/tools.jar ファイルに含まれています。このファイルには、これらのインタフェースを実装するクラスが含まれる private パッケージも入っています。さらに、tools.jar ファイルには、標準ドックレットを実装したクラスも含まれています。
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;
}
}
ドックレットに関して最初に注意するべき点は、ドックレット 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 を含める必要があります。
ListClass ドックレットを実行するには、コンパイルしたドックレットを javadoc の -doclet および -docletpath タグで指定します。たとえば、このドックレットを MyClass.java というファイルに対して実行するには、次のコマンドを使用します (ListClass.class が現在のディレクトリ内にあると想定)。javac -classpath C:\jdk1.3\lib\tools.jar ListClass.java
出力は、「MyClass」という文字列になります。このコマンドを使用するとき、tools.jar をクラスパス上に置く必要はありません。そのファイルは、javadoc ツールが自動的にロードするからです。% javadoc -doclet ListClass -docletpath . MyClass.java
コマンド行オプションについての注意: javadoc -help を実行するとわかるように、Javadoc ツールにはコマンド行オプションが 2 セットあります。一方のセットは汎用で、どのドックレットでも使用できます。もう一方のセットは、標準ドックレット専用で、カスタムドックレットを使う場合には利用できません。カスタムドックレットでは、ドックレット独自のコマンド行オプションを定義することもできます。このあとの例を参照してください。
API ドキュメントを生成するには、ドックレットは、この簡単な例よりもかなり複雑になります。javadoc で生成する API ドキュメントの形式をカスタマイズする場合は、ドックレットを自分でゼロから作成するよりも、デフォルトの標準ドックレットに修正を加える形で作成したほうが簡単です。
実例は、「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")
この場合、text メソッドは、「Some dummy text.」という文字列を返します。@mytag 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());
}
}
}
}
}
}
カスタムオプションを使用するドックレットには、int 型の値を返す optionLength(String option) というメソッドが必要です。optionLength は、ドックレットが認識するカスタムオプションごとに、そのオプションを構成する要素 (トークン) の数を返さなければなりません。ここでは、-tag mytag という形式のカスタムオプションを使用できるようにしてみます。このカスタムオプションは、-tag オプションそのものとその値という 2 つの要素で構成されるので、作成するドックレットの optionLength メソッドは、-tag オプションに対しては 2 を返さなければなりません。また、認識できないオプションに対しては、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;
}
}
さらに、このドックレットには、コマンド行オプションを解析して -tag オプションを探す readOptions メソッドも追加されています。このメソッドでは、オプションの情報が含まれた String 型の 2 次元配列を返す Rootdoc.options メソッドを利用しています。たとえば、次のコマンドを実行するとします。
RootDoc.options メソッドは次の戻り値を返します。javadoc -foo this that -bar other ...
配列の 2 番目の添え字に入っている要素数は、optionLength メソッドにより判別されます。この例では、optionLength は、-foo オプションに対しては 3 を返し、-bar オプションに対しては 2 を返します。options()[0][0] = "-foo" options()[0][1] = "this" options()[0][2] = "that" options()[1][0] = "-bar" options()[1][1] = "other"
validOptions メソッドは、コマンド行タグの指定が正しいかどうかをチェックするための、省略可能なメソッドです。validOptions メソッドは、存在すれば自動的に呼び出されるため、明示的に呼び出す必要はありません。このメソッドでは、オプションの指定が正しい場合は true を返し、そうでない場合は false を返すようにします。また、指定の正しくないコマンド行オプションが見つかった場合に、validOptions から適切なエラーメッセージを表示することもできます。このドックレットの validOptions メソッドでは、-tag オプションが 1 つ指定されているかどうか、そして 2 つ以上指定されていないかどうかをチェックしています。
|
Copyright © 1995-98 Sun Microsystems, Inc. All Rights Reserved. コメントの送付先:
|
|