モジュール jdk.javadoc

パッケージ com.sun.javadoc

ノート: このパッケージの宣言は、パッケージjdk.javadoc.docletの宣言に置き換えられました。 詳細は、そのパッケージのマニュアルの「移行ガイド」を参照してください。

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

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

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

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

用語

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

ClassDoc、allClasses()、および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は、ドックレットの呼出しインタフェースを指定する抽象クラスです。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