ドックレットは、次の基本手順に従って作成し、使用します。
コマンド行オプション-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; } }コードから推察できるように、このドックレットは、javadocの処理対象となるクラスについて、その名前を標準出力に書き出します。
ドックレットに関して最初に注意するべき点は、ドックレットAPIを使用できるようにするためにcom.sun.javadocパッケージをインポートしなければならないということです。エントリ・ポイントは、どのドックレットの場合にもpublic static boolean startメソッドです。startメソッドは、パラメータとしてRootDocを取ります。このパラメータには、javadocの実行時にコマンド行に指定されたオプションと、javadocの処理対象となるクラスとパッケージについての情報が入っています。
RootDocは、classesというメソッドを定義しています。このメソッドからは、ClassDoc配列が返されますが、この配列の要素はjavadocが解析するクラスを表しています。次に、forループで、配列に含まれる各クラスの名前を出力します。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ドキュメントの形式をカスタマイズする場合は、ドックレットを自分でゼロから作成するよりも、デフォルトの標準ドックレットに修正を加える形で作成した方が簡単です。
実例は、「How can I modify the standard doclet to produce links to source code from the API documentation?」を参照してください。
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つ以上指定されていないかどうかをチェックしています。