モジュール 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