ドックレット API

パッケージ com.sun.javadoc

ドックレット API (Javadoc API とも言う) は、ソースに埋め込まれた javadoc コメントを含む、プログラムとライブラリのソースレベルの構造を検証するメカニズムをクライアントに提供します。

参照: 説明

パッケージ com.sun.javadoc の説明

ドックレット API (Javadoc API とも言う) は、ソースに埋め込まれた javadoc コメントを含む、プログラムとライブラリのソースレベルの構造を検証するメカニズムをクライアントに提供します。ドックレット API は、ドキュメンテーション、プログラムチェック、自動コード生成、およびほかの多くのツールで役に立ちます。

ドックレットは javadoc により呼び出され、この API を使ってプログラム情報をファイルに書き出します。たとえば、標準的なドックレットはデフォルトで呼び出され、HTML ファイルにドキュメンテーションを書き出すことができます。

この呼び出しは、抽象 Doclet クラスにより定義されます。エントリポイントは、次の start メソッドです。

    public static boolean start(RootDoc root)
RootDoc インスタンスは、プログラム構造情報のルートを保持します。このルートから、ほかのすべてのプログラム構造情報を取り出すことができます。

用語

javadoc の呼び出し時に、パッケージ名とソースファイル名を渡します。これらは、指定されたパッケージおよびクラスと呼ばれます。また、Javadoc オプションも渡します。アクセス制御 Javadoc オプション (-public-protected-package、および -private) を指定すると、プログラム要素がフィルタ処理され、含まれるセットまたは「ドキュメント化された」セットと呼ばれる結果セットが生成されます。(フィルタ処理されていないセットも、allClasses(false) 経由で使用できます。)

ClassDocallClasses()、および findClass(String) で示されているように、この API ではクラスという用語は通常「クラスまたはインタフェース」の略として使用されます。Doc.isClass() で示されているように、「インタフェースの対語としてのクラス」を意味することはまれです。2 つの目の意味では、この API は通常クラス列挙型エラー、および例外の 4 種類のクラスを呼び出します。この API では、各プログラム要素の詳細な説明で、どの意味が使われているかを明示的に示しています。

修飾クラス名またはインタフェース名とは、パッケージ名が付加された名前です (java.lang.String など)。修飾されていない名前には、パッケージ名が含まれません (String など)。

処理対象クラスの @param タグ内の情報を表示するドックレットの例を次に示します。
import com.sun.javadoc.*;

public class ListParams extends Doclet {

    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            ClassDoc cd = classes[i];
            printMembers(cd.constructors());
            printMembers(cd.methods());
        }
        return true;
    }

    static void printMembers(ExecutableMemberDoc[] mems) {
        for (int i = 0; i < mems.length; ++i) {
            ParamTag[] params = mems[i].paramTags();
            System.out.println(mems[i].qualifiedName());
            for (int j = 0; j < params.length; ++j) {
                System.out.println("   " + params[j].parameterName()
                    + " - " + params[j].parameterComment());
            }
        }
    }        
}
Javadoc API のインタフェースおよびメソッドは、赤色で示されています。Doclet は、ドックレットの呼び出しインタフェースを指定する abstract クラスです。Doclet には、クラス情報またはインタフェース情報が保持されます。ExecutableMemberDoc は、MethodDoc および ConstructorDoc のスーパーインタフェースであり、ParamTag には、「@param」タグから得た情報が保持されます。

コマンド行で次のように指定して、このドックレットを呼び出すとします。

    javadoc -doclet ListParams -sourcepath <source-location> java.util
次のような出力が生成されます。
    ...
    java.util.ArrayList.add
       index - index at which the specified element is to be inserted.
       element - element to be inserted.
    java.util.ArrayList.remove
       index - the index of the element to removed.
    ...

関連項目:
Doclet, RootDoc
ドックレット API

バグまたは機能を送信
Java は米国ならびにその他の国における Oracle Corporation およびその関連企業の商標または登録商標です。
Copyright © 1993, 2013, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.