標準ドックレット

標準ドックレットの概要

標準ドックレットは、Sun^TM が提供するドックレットで、Javadoc のデフォルトの HTML 形式による API 出力を生成します。この SDK ドキュメントに含まれる Java^TM プラットフォームの API ドキュメントは、標準ドックレットによる出力の例です。 Javadoc の -doclet オプションを使ってコマンド行で他のドックレットが指定されていない場合は、標準ドックレットが使われます。

標準ドックレットに注目する 1 番目の理由は、ドックレット API を最大限に利用した良い例であることが挙げられます。 2 番目の理由は、標準ドックレットがデフォルトの HTML 出力をどのように生成するかを知ることにより、標準ドックレットを修正して、カスタム API ドキュメントを生成する独自のドックレットを作成しやすくなることです。

標準ドックレットのクラス

標準ドックレットは、com.sun.tools.doclets パッケージ、 com.sun.tools.doclets.standard および com.sun.tools.doclets.standard.tagsパッケージのクラスで構成されています。デフォルトの HTML 出力を生成するうえで、重要な役割を果たす標準ドックレットのクラスの概要を次に示します。

com.sun.tools.doclets

HtmlWriter - HTML 形式の出力を生成するために必要な各種 HTML タグを作成する API を含むクラスです。
HtmlDocWriter - HtmlWriter クラスを拡張したクラスで、デフォルトの HTML 出力で使われる特殊なハイパーリンクを生成するための HTML 関連 API が追加されています。たとえば、HTML ページのヘッダとフッタの中のリンクを生成します。
タグレット - タグの出力形式を指定するクラスを表すインタフェースです。タグレットを展開し、カスタムタグの出力形式を指定できます。タグレットの詳細については、「タグレットの概要」を参照してください。
TagletManager - ドックレットが使用しているタグレットを管理するクラスです。タグレットの登録、取得、また、タグが TagletManager (エラーチェックに使用) で認識されているかどうかを確認するためのメソッドがあります。 TagletManager は、間違った場所で使用されているタグがないかも確認します。たとえば、@param タグがクラスドキュメンテーション内で使用されている場合、警告メッセージが表示されます。@param タグを使用できるのは、コンストラクタおよびメソッドドキュメンテーション内のみだからです。

com.sun.tools.doclets.standard

Standard - このクラスには start メソッドが含まれており、標準ドックレットのエントリポイントになります。 javadoc が処理対象にするパッケージやクラスについて HTML 形式の API ファイルを生成する処理の調整を図ります。
PackageIndexWriter - javadoc のコマンド行で指定されたパッケージすべてのリストを含む overview-summary.html ファイルを生成します。生成されるファイルのサンプルは、この Java Development Kit の API ドキュメントにある overview-summary.html ファイルを参照してください。
PackageIndexFrameWriter - overview-frame.html ファイルを生成します。このファイルは、フレーム形式のデフォルト出力の左上のフレームに、パッケージリンクのリストを表示するために使われます。この SDK ドキュメントの API ドキュメントにある overview-frame.html ファイルを参照してください。
PackageFrameWriter - package-frame.html ファイルを生成します。このファイルは、フレーム形式のデフォルト出力の左下のフレームに、特定のパッケージのインタフェースとクラスのリストを表示するために使われます。例としては、このリリースのプラットフォーム API ドキュメントに含まれる java.awt の package-frame.html ファイルを参照してください。
FrameOutputWriter - index.html ファイルを生成します。このファイルは、API ドキュメントのフレーム形式の「表紙ページ」を表示するために使われます。例としては、プラットフォーム API ドキュメントの index.html ファイルを参照してください。
PackageWriter - package-summary.html ファイルを生成します。このファイルには、特定のパッケージのインタフェースとクラスが表示されます。例としては、このリリースの API ドキュメントの java.lang の package-summary.html ページを参照してください。
ClassWriter - 個々のインタフェースおよびクラスについて、HTML 形式の API ドキュメントを生成します。例としては、Java 2 プラットフォーム API ドキュメントの Font.html ファイルを参照してください。
SingleIndexWriter - -splitindex オプションが指定されていないときに、標準ドックレットが生成するクラスメンバについて、単一のインデックスファイルを生成します。
SplitIndexWriter - Javadoc がコマンド行オプション -splitindex を指定して標準ドックレットを実行したときに生成されるクラスメンバについて、複数のインデックスファイルを生成します。インデックスファイルには、index-1.html のように、番号が付けられます。
TreeWriter - overview-tree.html ファイルを生成します。このファイルには、標準ドックレットの処理対象になったクラスのクラス階層が表示されます。例としては、Java 2 プラットフォーム API ドキュメントの overview-tree.html ファイルを参照してください。
DeprecatedListWriter - deprecatedlist.html ファイルを生成します。このファイルには、推奨されない API が表示されます。例としては、このリリースの API ドキュメントの deprecated-list.html ファイルを参照してください。
ClassUseMapper、ClassUseWriter、および PackageUseWriter - これらのクラスは、クラスおよびパッケージの「Use」ファイルを生成します。ナビゲーションバーの [使用] リンクをクリックすると、クラスまたはパッケージの [使用] ページに移動します。たとえば、Character クラスおよび java.lang パッケージには、このようなページがあります。
PackageListWriter - API ドキュメントの最上位ディレクトリに置かれる package-list テキストファイルを生成します。このファイルは、標準ドックレットの -link コマンド行オプションで使用するために必要です。標準ドックレットの Extern クラスも、-link オプションが機能するための役割を果たします。このオプションの詳細については、Javadoc のリファレンスページ ([Windows] [Solaris]) を参照してください。
Group - このクラスは、overview-summary.html ページでパッケージを 1 つまたは複数のテーブルにグループ化します。このクラスは、標準ドックレットの -group コマンド行オプションをサポートします。このオプションの詳細については、Javadoc のリファレンスページ ([Windows] [Solaris]) を参照してください。

com.sun.tools.doclets.standard.tags

AbstractExecutableMemberTaglet - 実行可能メンバのドキュメンテーションで使用されるタグの出力形式を指定する抽象タグレットです。
AbstractInlineTaglet - インラインタグの出力形式を指定する抽象タグレットです。独自のカスタムインラインタグを作成する場合は、この抽象クラスをサブクラスにする必要があります。
DocRootTaglet - {@docRoot} の出力形式を指定するタグレットです。
InheritDocTaglet - {@inheritDoc} の出力形式を指定するタグレットです。
ParamTaglet - @param の出力形式を指定するタグレットです。
ReturnTaglet - @return の出力形式を指定するタグレットです。
SeeTaglet - @see の出力形式を指定するタグレットです。
SimpleTaglet - @author や @version のように 1 つの引数をとるタグの出力形式を指定するタグレットです。
ThrowsTaglet - @throws の出力形式を指定するタグレットです。
ValueTaglet - {@value} の出力形式を指定するタグレットです。

タグレットの詳細については、「タグレットの概要」を参照してください。

コマンド行からの標準ドックレットの実行

コマンド行で-doclet タグが他のドックレットを指定していない場合は、デフォルトで標準ドックレットが呼び出されます。たとえば、次のコマンドを実行するとします。

% javadoc myPackage

標準ドックレットを使って、myPackage についての HTML 形式 (デフォルトのスタイル) の API ドキュメントが生成されます。 -doclet オプションを指定しないで javadoc を実行した場合は、-doclet オプションを指定して標準ドックレットを呼び出した場合と同じ処理が行われます。つまり、上記のコマンドは、次のコマンドと同義です。

% javadoc -doclet com.sun.tools.doclets.standard.Standard myPackage

プログラムからの標準ドックレットの実行

Javadoc ツールには、プログラムから利用できるインタフェースがあります。このインタフェースには、Java 言語で記述された別のプログラムから Javadoc ツールを呼び出すための public メソッドがいくつか用意されています。これらのメソッドは、com.sun.tools.javadoc.Main クラスにあります。

public static void main(java.lang.String[] args)

コマンド行インタフェースです。

パラメータ:
args - コマンド行パラメータ

public static int execute(java.lang.String[] args)

プログラムから利用できるインタフェースです。
パラメータ:
args - コマンド行パラメータ
戻り値:
リターンコード

public static int execute(java.lang.String programName,
                          java.lang.String[] args)

プログラムから利用できるインタフェースです。
パラメータ:
programName - プログラムの名前 (エラーメッセージ用)
args - コマンド行パラメータ
戻り値:
リターンコード

public static int execute(java.lang.String programName,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)

プログラムから利用できるインタフェースです。
パラメータ:
programName - プログラムの名前 (エラーメッセージ用)
defaultDocletClassName - 完全指定のクラス名
args - コマンド行パラメータ
戻り値:
リターンコード

public static int execute(java.lang.String programName,
                          java.io.PrintWriter errWriter,
                          java.io.PrintWriter warnWriter,
                          java.io.PrintWriter noticeWriter,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)

プログラムから利用できるインタフェースです。
パラメータ:
programName - プログラムの名前 (エラーメッセージ用)
errWriter - エラーメッセージを受け取る PrintWriter
warnWriter - エラーメッセージを受け取る PrintWriter
noticeWriter - エラーメッセージを受け取る PrintWriter
defaultDocletClassName - 完全指定のクラス名
args - コマンド行パラメータ
戻り値:
リターンコード