ドックレット API

パッケージ com.sun.javadoc

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

参照先:
          説明

インタフェースの概要
AnnotationDesc 注釈を表します。
AnnotationDesc.ElementValuePair 注釈型の要素とその要素の値 (1 つ) との関連を表します。
AnnotationTypeDoc 注釈型を表します。
AnnotationTypeElementDoc 注釈型の要素を表します。
AnnotationValue 注釈型の要素の値を表します。
ClassDoc 特定の Java クラスまたはインタフェースを表し、クラス、クラスのコメントとタグ、およびクラスのメンバに関する情報へのアクセスを提供します。
ConstructorDoc 特定の Java クラスの特定のコンストラクタを表します。
Doc Java 言語構造要素 (パッケージ、クラス、コンストラクタ、メソッド、フィールド) を表します。
DocErrorReporter エラー、警告、および通知の表示機能を提供するインタフェースです。
ExecutableMemberDoc 特定の Java クラスの特定のメソッドまたはコンストラクタを表します。
FieldDoc 特定の Java クラス内の特定のフィールドを表します。
MemberDoc 特定の Java クラスの特定のメンバ (フィールド、コンストラクタ、メソッドのどれか) を表します。
MethodDoc 特定の Java クラスの特定のメソッドを表します。
PackageDoc 特定の Java パッケージを表します。
Parameter パラメータ情報 (パラメータの型と名前) です。
ParameterizedType 汎用クラスまたは汎用インタフェースの呼び出しを表します。
ParamTag 特定のドキュメンテーションタグ @param を表し、パラメータタグの名前の部分とコメントの部分を格納します。
ProgramElementDoc Java プログラムの特定の要素 (クラス、インタフェース、フィールド、コンストラクタ、メソッドのどれか) を表します。
RootDoc javadoc の特定の実行に関するプログラム構造情報のルートを表します。
SeeTag 関連するドキュメンテーションへのユーザ定義相互参照を表します。
SerialFieldTag ObjectStreamField によって定義される Serializable フィールドのドキュメントを作成します。
SourcePosition このインタフェースはソース位置を記述します。
Tag 単純なドキュメンテーションタグ (@since、@author、@version など) を表します。
ThrowsTag 特定のドキュメンテーションタグ @throws または @exception を表します。
Type 特定の型を表します。
TypeVariable 型変数を表します。
WildcardType ワイルドカード型引数を表します。
 

クラスの概要
Doclet この例は、ドックレットの起動クラスの例として、エントリポイントメソッドを示しています。
 

列挙型の概要
LanguageVersion Java プログラミング言語バージョン。
 

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

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

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

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

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

用語

javadoc の呼び出し時は、パッケージ名とソースファイル名を渡します。これらは、「指定された」パッケージとクラスと呼ばれます。また、Javadoc オプションも渡します。アクセス制御 Javadoc オプション (-public-protected-package、 および -private) は、プログラム要素をフィルタ処理し、「組み込み」セットまたは「ドキュメント化」セットと呼ばれる結果セットを生成します。フィルタ処理されていない セットも allClasses(false) で利用可能です。 ClassDocallClasses()findClass(String) で示されているように、この API を通じて、「クラス」という用語は通常「クラスまたはインタフェース」の略として使用されています。ほんのいくつかの箇所では、Doc.isClass() で示されているように、クラスは「インタフェースの反意語としてのクラス」を意味します。この意味では、API は次の 4 種類のクラスを呼び出します。ordinary classesenumserrorsexceptions です。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 はクラスもしくはインタフェースの情報を保持し、ExecutableMemberDocMethodDoc のスーパーインタフェースで、ConstructorDocParamTag は、@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 は、米国およびその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 1993-2004 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.