3 Javadocコマンド
javadoc
コマンド行の形式はjavadoc [options] [packagenames] [sourcefiles] [@files]
です。オプションはドックレット・オプションまたは標準ドックレット・オプションです。javadoc
コマンドはプログラムで実行することもできます。
Javadocのドックレット
javadoc
ツールおよびそのオプションを使用して、Javaソース・ファイルからAPIドキュメントのHTMLページを生成します。
Javadocドックレットのオプション
javadoc
コマンドにはドックレットのオプションがあります。標準ドックレットには追加のオプションがあります。
javadoc
コマンドは、ドックレットを使用してその出力を決定し、-doclet
オプションでカスタム・ドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使用します。オプション名は大文字と小文字が区別されませんが、その引数では大文字と小文字が区別されます。オプションは、Java Development Kitツール仕様のjavadocコマンドに関する項で説明されています。
ソース・ファイルの処理
javadoc
コマンドは、末尾にファイル拡張子sourceが付いたファイル以外に、ソース・ファイルで説明する他のファイルも処理します。個々のソース・ファイル名を渡すことによってjavadoc
コマンドを実行する場合、どのソース・ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソース・ファイル名を明示的に指定しなくても、javadoc
コマンドは3つの方法で実行できます。この方法は、パッケージ名を渡す、-subpackages
オプションを使用する、ソース・ファイル名にワイルドカードを使用するという方法です。これらの方法を使用する場合、javadoc
コマンドは、ソース・ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。
-
ファイル名の接頭辞(
.java
を取り除いたもの)が、有効なクラス名になっている。 -
ソース・ツリーのルートからの相対的なパス名が、区切り文字をドットに変換すると、有効なパッケージ名になっている。
-
パッケージ文には有効なパッケージ名が含まれている。
リンクの処理
javadoc
コマンドは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、相互参照リンクを追加します。このようなリンクは、次の場所に追加されます。
-
宣言(戻り値の型、引数の型、およびフィールドの型)
-
@seeタグから生成された
関連項目
セクション -
{@link}
タグから生成されたインライン・テキスト -
@throws
タグから生成された例外の名前 -
インタフェースのメンバーに対する「定義」リンクと、クラスのメンバーに対する「オーバーライド」リンク
-
パッケージ、クラス、およびメンバーを列挙しているサマリー表
-
パッケージおよびクラスの継承ツリー
-
索引
処理詳細
javadoc
コマンドは、実行するたびに1つの完全なドキュメントを作成します。以前の実行結果を変更したり直接組み入れたりする追加生成は実行しません。ただし、javadoc
コマンドでは、以前の実行結果に対してリンクを追加することはできます。
javadoc
コマンドの実装は、Javaコンパイラを必要とし、Javaコンパイラに依存しています。javadoc
コマンドは、javac
コマンドの一部を呼び出すことによって宣言をコンパイルし、メンバーの実装は無視します。javadoc
コマンドは、クラス階層を含むクラスの豊富な内部表現とクラスの使用関係を構築して、HTMLドキュメントを生成します。さらに、javadoc
コマンドは、ソース・コードのドキュメンテーション・コメントから、ユーザーの提供したドキュメントも取得します。
javadoc
コマンドは、メソッド本体のない純粋なスタブ・ファイルであるソース・ファイル上で実行できます。したがって、APIの実装を記述する前の設計の早い段階で、ドキュメンテーション・コメントを記述してjavadoc
コマンドを実行できます。
コンパイラに依存することによって、HTML出力は、実際の実装に正確に対応します。実際の実装は、明示的なソース・コードにではなく、暗黙のソース・コードに依存する場合があります。たとえば、javadoc
コマンドは、コンパイル済みクラス・ファイル内に存在するが、ソース・コード内には存在しないデフォルト・コンストラクタをドキュメント化します。
通常、javadoc
コマンドでは、ソース・ファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。任意のデバッグやトラブルシューティングを完了する前にドキュメントを生成できます。javadoc
コマンドはドキュメンテーション・コメントの基本的なチェックを行います。
javadoc
コマンドは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、javadoc
コマンドは、すべての参照クラスを検索でき、かつそれがブートストラップ・クラス、拡張機能、ユーザー・クラスのいずれであるか判別できる必要があります。
Javadocのドックレット
javadoc
コマンドの出力の内容と形式は、ドックレットを使ってカスタマイズできます。javadoc
コマンドには、標準ドックレットと呼ばれるデフォルトの組込みドックレットがあります。標準ドックレットは、HTML形式のAPIドキュメントを生成します。HTML、XML、MIF、RTFなどの好みの出力形式を生成する独自のドックレットを記述できます。
-doclet
オプションでカスタム・ドックレットが指定されていない場合、javadoc
コマンドは、デフォルトの標準ドックレットを使用します。javadoc
コマンドには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらの他に、いくつかのコマンド行オプションが追加されます。
linkオプションの使用
-link
オプションは、「コードからは参照されていても、javadoc
コマンドの今回の実行ではドキュメント化されない」というクラスにリンクするのに使用します。
リンクから有効なページに移動できるようにするには、それらのHTMLページがある場所を調べ、その場所をextdocURL
に指定する必要があります。これにより、サードパーティのドキュメントをJavaにリンクできます。javadoc
コマンドにより、今回の実行で生成されるドキュメント内のAPIのみを対象にリンクを作成する場合は、-link
オプションを省略します。-link
オプションが指定されていないと、javadoc
コマンドは、外部参照のドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所がわからないからです。-link
オプションでは、生成ドキュメント内の複数の場所にリンクを作成できます。「Javadocのドックレット」を参照してください。また、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対してjavadoc
コマンドを実行した後、別の一式のパッケージに対してjavadoc
コマンドを実行し、これら2つのパッケージ群の間に双方向のリンクを作成できます。
-linkオプションと-linkofflineオプションの相違点
-link
オプションは次の場合に使用します。
-
外部APIドキュメントへの相対パスを使用する場合。
-
外部APIドキュメントへの絶対URLを使用する場合で、そのURLに対して読取り用の接続を開くことがシェルによって許可されているとき。
外部APIドキュメントへの絶対URLを使用する場合で、プログラムがそのURLに対して読取り用の接続を開くことがシェルによって許可されていないときは、-linkoffline
オプションを使用します。このような状況は、ファイアウォールの内側からファイアウォールの外側にあるドキュメントにリンクしようとする場合に発生します。
例3-1 外部ドキュメントへの絶対リンクの使用の例
java.lang
、java.io
およびその他のJavaプラットフォーム・パッケージへのリンクを作成するには、次のコマンドを使用します。
javadoc -link https://docs.oracle.com/javase/8/docs/api/com.mypackage
このコマンドは、Java SEパッケージへのリンクを含む、com.mypackage
パッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラス・ツリー
内のObject
クラスへのリンクが含まれています。-sourcepath
や-d
などの他のオプションは表示されません。
例3-2 外部ドキュメントへの相対リンクの使用の例
-
この例では、2つのパッケージがあり、そのドキュメントが
javadoc
コマンドを複数回実行して生成されているとします。さらに、これらのドキュメントが相対パスで分割されているとします。 -
パッケージは、API である
com.apipackage
と、SPI (サービス・プロバイダ・インタフェース)であるcom.spipackage
です。 -
ドキュメントの格納先は、
docs/api/com/apipackage
とdocs/spi/com/spipackage
です。 -
APIパッケージのドキュメントがすでに生成されていて、現在のディレクトリがdocsである場合、このAPIドキュメントへのリンクを持つSPIパッケージをドキュメント化するには、
javadoc -d ./spi -link ../api com.spipackage
を実行します。注意:
-link
オプションは生成先ディレクトリ(docs/spi
)を基準にしています。
クラスの参照方法
外部参照クラスのテキスト・ラベルだけではなくリンクを表示するには、特定の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するのみでは十分ではありません。import
文または宣言のいずれかで参照する必要があります。
-
すべての種類のインポート文の場合。ワイルドカードによるインポート、名前による明示的なインポート、または
java.lang.*
に対する自動的なインポート。 -
宣言の場合:
void mymethod(File f) {}
参照は、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、
implements
、extends
、またはthrows
文に置くことができます。-link
オプションを使用しても、誤って表示されないリンクが多数発生する可能性があります。テキストはリンクが付けられずに表示されます。これらが表示する警告から、このようなテキストを認識できます。クラスを正しく参照してリンクを追加するための最も簡単な方法は、当該のクラスをインポートすることです。
宣言の場合: void mymethod(File f) {}
パッケージ・リスト
-link
オプションを使用するには、javadoc
コマンドによって生成されたpackage-list
という名前のファイルが、-link
オプションで指定するURLに存在している必要があります。JDK 8では、package-list
ファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキスト・ファイルです。
-link
オプションを指定せずにjavadoc
を実行した場合、外部参照クラスに属する名前を見つけると、javadocはその名前をリンクを持たない形で出力します。一方、-link
オプションを指定した場合は、javadoc
コマンドは指定したextdocURLにあるpackage-list
ファイルから該当するパッケージ名を検索します。パッケージ名が見つかると、extdocURL
が名前の前に付加されます。
すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定したURLに存在していなければなりません。javadoc
コマンドは、指定されたpackage-listが存在するかどうかを調べるだけで、指定された場所に目的のページが存在するかどうかはチェックしません。
複数のリンク
複数の-link
オプションを指定すると、生成された任意の数の外部ドキュメントに対してリンクを設定できます。リンクする外部ドキュメントごとに、javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn com.mypackage
のように別々のリンク・オプションを指定します。extdocURL1
、extdocURL2
、... extdocURLn
は、それぞれ外部ドキュメントのルートを指し、各ルートにはpackage-list
という名前のファイルが入っています。
クロスリンク
注意:
以前に生成された複数のドキュメントをクロスリンクする場合は、ブートストラップが必要になります。どのドキュメントについてもpackage-list
ファイルが存在していない場合は、最初のドキュメントに対してjavadoc
コマンドを実行する時点で、2番目のドキュメントのpackage-listがまだ存在していません。したがって、外部リンクを作成するには、2番目のドキュメントを生成した後で、最初のドキュメントを生成し直す必要があります。
この場合、最初のドキュメント生成の目的は、そのドキュメントのpackage-listを作成することです。パッケージ名をすべて把握している場合は、package-listを手動で作成することもできます。次に、2番目のドキュメントとその外部リンクを生成します。必要な外部のpackage-list
ファイルが存在しない場合、javadoc
コマンドは警告を出力します。
linkofflineオプションの使用
java.lang
、java.io
およびその他のJava SEパッケージにリンクするにはlinkoffline
オプションを使用します
外部ドキュメントへの絶対リンク
java.lang
、java.io
、およびその他のJava SEパッケージにリンクする場合について考えます。ただし、シェルからWebにアクセスできないとします。この場合は、次のようにします。
-
API仕様にある
package-list
ファイルをブラウザで開きます。 -
このファイルをローカル・ディレクトリに保存し、2番目の引数
packagelistLoc
にこのローカル・コピーの場所を指定します。この例では、パッケージ・リスト・ファイルはカレント・ディレクトリに保存されています。
次のコマンドは、Java SEパッケージへのリンクを含む、com.mypackage
パッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラス・ツリー
内のObject
クラスへのリンクが含まれています。-sourcepath
などの他の必要なオプションは表示されません。
javadoc -linkoffline https://docs.oracle.com/javase/8/docs/api/.com.mypackage
外部ドキュメントへの相対リンク
-linkoffline
に相対パスを使用することは一般的ではありません。通常は-link
オプションで十分だからです。-linkoffline
オプションを使用する場合、package-listファイルは通常はローカル・ファイルです。また、相対リンクを使用する場合、リンク先のファイルもローカル・ファイルです。したがって、通常は、-linkoffline
オプションの2つの引数に別々のパスを指定する必要はありません。2つの引数が同一である場合は、-link
オプションを使用できます。
package-listファイルの手動での作成
package-list
ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルを自分で作成し、packagelistLoc
でそのパスを指定できます。その例が、com.spipackage
が最初に生成されたときに、com.apipackage
のpackage-list
ファイルが存在しないという場合です。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。同様に、2つの会社が未公開のpackage-list
ファイルを共有することもできるため、クロスリンクを設定したドキュメントを同時にリリースすることも可能です。
複数ドキュメントへのリンク
-linkoffline
オプションは、参照先の生成ドキュメントごとに1つずつ指定できます。
javadoc -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2
packagelistLoc2 ...
ドキュメントの更新
-linkoffline
オプションは、プロジェクトに大量のパッケージが含まれている場合にも使用できます。すでにツリー全体に対してjavadoc
コマンドの実行が完了している場合に、ドキュメンテーション・コメントに少量の変更を手早く加えた後、ソース・ツリーの一部に対してだけjavadoc
コマンドを再実行することができます。ただし、2回目の実行が正しく機能するのは、ドキュメンテーション・コメントに対して変更を加え、宣言は変更していない場合だけです。ソース・コードの宣言を追加、削除、または変更した場合は、索引、パッケージ・ツリー、継承されるメンバーのリスト、「使用」ページなどの場所で、リンクが壊れることがあります。
まず、今回の実行で使用する新しい生成先ディレクトリ(update
など)を作成します。この例では、元の生成先ディレクトリの名前はhtml
です。最も単純な例では、html
ディレクトリの親ディレクトリに移動します。-linkoffline
オプションの最初の引数にカレント・ディレクトリを指定し、2番目の引数にhtml
への相対パスを指定し(ここでpackage-list
ファイルが検索されます)、更新対象のパッケージのパッケージ名だけを指定します。
javadoc -d update -linkoffline . html com.mypackage
LinuxおよびmacOS: javadoc
コマンドの実行が完了したら、update/com/package
内に生成されたクラス・ページをコピーし(概要、索引ではない)、html/com/package
内の元のファイルを上書きします。
Windows: javadoc
コマンドが完了したら、これらの生成されたクラス・ページをupdate\com\package
(概要や索引ではない)にコピーし、html\com\package
内の元のファイルにコピーします。
タグ・オプションの使用
Xaoptcmf
引数を使用して、ソース・コード内のタグを配置できる位置と、X
を使ってこのタグを無効にできるかどうかを特定します。
タグの配置
タグの配置位置を制限しない場合はa
を指定します。それ以外の文字の組み合わせも可能です。
-
X
(タグの無効化) -
a
(すべて) -
o
(概要) -
p
(パッケージ) -
t
(型すなわちクラスおよびインタフェース) -
c
(コンストラクタ) -
m
(メソッド) -
f
(フィールド) -
s
(モジュール)
シングル・タグの例
ソース・コード内の任意の位置で使用できるタグのタグ・オプションの例を示します。-tag todo:a:"To Do:"
@todo
タグをコンストラクタ、メソッド、フィールドのみで使用する場合は、以下のオプションを使用します。-tag todo:cmf:"To Do:"
最後のコロン(:)は、パラメータ区切り文字ではなく、見出しテキストの一部になっています。次の例のように、@todo
タグを含むソース・コードでは、いずれかのタグ・オプションを使用できます。@todo The documentation for this method needs work
タグ名内のコロン
タグ名内でコロンを使用する場合はバックスラッシュを使用してエスケープします。次のドキュメンテーション・コメントには、-tag ejb\\:bean:a:"EJB Bean:"
オプションを使用します。
/**
* @ejb:bean
*/
タグ名のスペルチェック
ソース・コード内に配置した一部のカスタム・タグの出力としての生成を抑制したい場合があります。この場合、ソース・コード内のすべてのタグをリストし、出力するタグを有効にし、出力しないタグを無効にする必要があります。X
を指定するとそのタグは無効になり、指定しないとそのタグは有効になります。これにより、javadoc
コマンドは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、javadoc
コマンドは警告を出力します。すでに配置されている値にX
を追加できます。こうしておけば、X
を削除するだけでタグを有効にすることができます。たとえば、@todo
タグの出力を抑制したい場合、次のように指定します。-tag todo:Xcmf:"To Do:"
さらに単純にするには、次のように指定します。-tag todo:X
構文-tag todo:X
は、@todo
タグがタグレットで定義されている場合も有効です。
タグの順序
-tag
および-taglet
オプションの順序によって、タグが生成される順序が決まります。カスタム・タグと標準タグを組み合わせて使用することもできます。標準タグのタグ・オプションは、順序を決定するためだけのプレースホルダーです。これらは標準タグ名のみを使用します。標準タグの小見出しは変更できません。たとえば、-tag
オプションがない場合、-taglet
オプションの位置によりその順序が決まります。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、-taglet
オプションと-tag
オプションの両方がtodo
という名前を持っている場合、コマンド行の最後にある方が順序を決定します。
タグの完全セットの例
この例では、出力のParameters
の後、Throws
の前にTo Do
を挿入します。また、X
を使用することにより、ソース・コードにおいて、この実行時に表示できない@example
タグがある可能性があることを指定しています。コマンド行で@argfile
を使用してオプションを含むファイルを指定する場合は、次のように、引数ファイル内の別々の行にタグを配置できます。行の継続を示す文字は不要です。
-tag param
-tag return
-tag todo:a:"To Do:"
-tag throws
-tag see
-tag example:X
javadoc
コマンドがドキュメンテーション・コメントを解析する際に検出されたタグのうち、標準タグでも-tag
や-taglet
オプションで渡されるタグでもないものは、未知のタグと見なされます。この場合、警告がスローされます。
標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。-tag
オプションを使用するたびに、そのタグがこのリストの末尾に追加されます。標準タグはそのデフォルト位置から移動されます。つまり、標準タグに-tag
オプションを付けなければ、これらはデフォルトの位置に配置されたままになります。
競合の回避
独自の名前空間を作成するには、com.mycompany.todo
のように、パッケージに使用されている命名規則に似たドット区切りの命名規則を使用します。Oracleは、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Oracleが定義する同じ名前のタグの動作をオーバーライドします。ユーザーが@todo
という名前のタグまたはタグレットを作成している場合、Oracleが後から同じ名前の標準タグを作成しても、そのタグまたはタグレットはユーザーが定義した元の動作を保持します。
注釈とJavadocタグの比較
通常、追加しようとしているマークアップの目的がドキュメントの変更または生成である場合は、Javadocタグにすべきです。そうでない場合は注釈にすべきです。How to Write Doc Comments for the Javadoc ToolのCustom Tags and Annotationsを参照してください。
-taglet
オプションを使用して、より複雑なブロック・タグやカスタム・インライン・タグを作成することもできます。
javadocコマンド行引数ファイル
javadoc
コマンドを短くしたり簡潔にしたりするために、javadoc
コマンドに対する引数(-J
オプションを除く)が入った1つ以上のファイルを指定します。このことを利用すれば、どのオペレーティング・システム上でも、任意の長さのjavadoc
コマンドを作成できます。
javadoc
コマンドを実行するときに、各引数ファイルのパスとファイル名を先頭に@
文字を付けて渡します。javadoc
コマンドは、@
文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。
例
- 単一の引数ファイル
-
argfile
という名前の引数ファイルにjavadoc
コマンドのすべての引数を格納できます:javadoc @argfile
。 - 2つの引数ファイル
-
引数ファイルには両方のファイルのコンテンツが格納されます。
javadoc
コマンドのオプション用に1つ、パッケージ名またはソース・ファイル名用に1つというように、2つの引数ファイルを作成することができます。なお、この後のリストでは、行の継続文字を使用していません。次の内容を含む、
options
という名前のファイルを作成します。LinuxおよびmacOS:
-d docs-filelist -use -splitindex -windowtitle 'Javadoc' -doctitle 'Javadoc Guide' -header '<b>Java™ SE </b>' -bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.' -group "Core Packages" "java.*" -overview /java/jdk9/docs/api/overview-summary -sourcepath /java/
Windows:
-d docs-filelist -use -splitindex -windowtitle 'Javadoc' -doctitle 'Javadoc Guide' -header '<b>Java™ SE 7</b>' -bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.' -group "Core Packages" "java.*" -overview \java\jdk9\docs\api\overview-summary.html -sourcepath \java\
次の内容を含む、
packages
という名前のファイルを作成します。com.mypackage1 com.mypackage2 com.mypackage3
javadoc
コマンドを次のように実行します。javadoc @options @packages
- パスを使用した引数ファイル
-
引数ファイルにはパスを指定できますが、ファイル内のすべてのファイル名は、現在の作業ディレクトリに相対的になります(
path1
やpath2
でなく)。LinuxおよびmacOS:
javadoc @path1/options @path2/packages
Windows:
javadoc @path1\options @path2\packages
- オプションの引数
-
次に、
javadoc
コマンド・オプションの引数を引数ファイルに保存する例を示します。ここでは、-bottom
を例に取り上げます。そのオプションには、かなり長い引数を指定することがあるからです。次のようなテキスト引数を含む、bottom
という名前のファイルを作成できます。<font size="-1"> <a href="http://bugreport.java.com/bugreport/">Submit a bug or feature</a> </font>
javadoc
コマンドを次のように実行します。javadoc -bottom @bottom @packages
また、引数ファイルの先頭に
-bottom
オプションを組み込んでおき、javadoc
コマンドを次のように実行することもできます。javadoc @bottom @packages
標準ドックレット
標準ドックレットは、Oracleが提供するドックレットで、JavadocのデフォルトのHTML形式によるAPI出力を生成します。
この項の内容は次のとおりです。
Javadoc標準ドックレット
-doclet
オプションを使用してコマンド行で他のドックレットが指定されていない場合は、標準ドックレットが使用されます。JDK 9以降、標準ドックレットでは、最新の言語機能をよりよく表す、より新しく強力なAPIを持つ更新済ドックレットAPIが使用されます。
標準ドックレットは、Oracleが提供するドックレットで、JavadocのデフォルトのHTML形式によるAPI出力を生成します。このJDKドキュメントに含まれるJavaプラットフォームのAPI仕様は、標準ドックレットの出力例です。
標準ドックレット・オプションは、Java Development Kitツール仕様のjavadocコマンドに関する項で説明されています。
-group name p1:p2
によって、指定されたパッケージが概要ページでグループ化されます。
-group groupheading packagepattern:packagepattern
では、概要ページのパッケージを指定のグループごとに、1つの表に1つのグループになるように分けます。各グループは、それぞれ別の-group
オプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。各グループ内では、パッケージがアルファベット順に並べられます。指定した-group
オプションごとに、packagepattern
式のリストと一致するパッケージが、見出しgroupheading
を持つ1つの表にまとめて表示されます。
-
groupheading
値には、任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。 -
packagepattern
の値には、任意のパッケージ名の先頭部分とそれに続く1つのアスタリスク(*)を指定できます。アスタリスクは使用できる唯一のワイルドカードであり、任意の文字に一致するという意味です。1つのグループには、コロン(:)で区切って複数のパターンを含めることができます。パターンやパターン・リスト内でアスタリスクを使う場合は、"java.lang*:java.util"
のように、パターン・リストを引用符で囲む必要があります。
-group
オプションが指定されていない場合は、すべてのパッケージが、「パッケージ」という見出しおよび適切な小見出しの1つのグループに入れられます。ドキュメント化されるパッケージの中に、指定したどの小見出しにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という小見出しを持つ独立したグループに入れられます。
たとえば、次のjavadoc
コマンドでは、ドキュメント化される3つのパッケージは、Core
、Extension
、およびOther Packages
に分けられます。java.lang*
には末尾のドット(.)がありません。java.lang.*
のようにドットを入れると、 java.lang
パッケージは除外されることになります。
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
コア・パッケージ
java.lang
java.lang.reflect
java.util
拡張機能パッケージ
javax.servlet
その他のパッケージ
java.new
生成されるファイル
javadoc
コマンドを、HTML形式のドキュメントを生成する標準ドックレットとして使用します。
標準ドックレットは、基本内容、相互参照、およびサポートのページを生成します。各HTMLページは個別のファイルに相当します。javadoc
コマンドは2種類のファイルを生成します。最初の種類には、クラスやインタフェースにちなんだ名前が付けられます。2番目の種類には、最初の種類のファイルと競合しないように、ハイフンが含まれています(package-summary.html
など)。
- 基本内容ページ
-
-
ドキュメント化するクラスまたはインタフェースごとに1つのクラス・ページまたはインタフェース・ページ(
classname.html
)。 -
ドキュメント化するパッケージごとに1つのパッケージ・ページ(
package-summary.html
)。javadoc
コマンドは、ソース・ツリーのpackage
ディレクトリ内にpackage.html
またはpackage-info.java
というファイルがあれば、その中のHTMLテキストをこのページに組み入れます。 -
パッケージのセット全体に対して1つの概要ページ(
overview-summary.html
)。概要ページは、生成ドキュメントの先頭ページになります。javadoc
コマンドは、-overview
オプションで指定されたファイル内のHTMLテキストをこのページに組み入れます。概要ページが作成されるのは、javadoc
コマンドに複数のパッケージ名を渡した場合のみです。HTMLフレームおよびJavadocドックレットのオプションを参照してください。
-
- 相互参照ページ
-
-
パッケージのセット全体に対して1つのクラス階層ページ(
overview-tree.html
)。階層ページを表示するには、ナビゲーション・バーの「概要」をクリックしてから、「階層ツリー」をクリックします。 -
各パッケージに対して1つのクラス階層ページ(
package-tree.html
)。特定のパッケージ、クラス、またはインタフェースのページを表示してから、「階層ツリー」をクリックすると、そのパッケージのクラス階層が表示されます。 -
パッケージごとに1つの「使用」ページ(
package-use.html
)と、クラスおよびインタフェースごとに1つの「使用」ページ(class-use/classname.html
)。「使用」ページには、指定されたクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。たとえば、クラスまたはインタフェースA
を例にすると、その使用ページには、A
のサブクラス、A
として宣言されたフィールド、A
を返すメソッド、A
型のパラメータを持つメソッドおよびコンストラクタが組み込まれます。「使用」ページを表示するには、そのパッケージ、クラスまたはインタフェースに移動し、ナビゲーション・バーの「使用」リンクをクリックしてください。 -
非推奨APIページ(
deprecated-list.html
)。すべての非推奨APIおよびそれに代わる推奨APIが一覧表示されます。非推奨APIは、将来の実装では削除される可能性があるため、使用しないようにしてください。定数フィールド値ページ(
constant-values.html
)。staticフィールドの値用です。 -
直列化された形式ページ(
serialized-form.html
)。直列化および外部化可能なクラスに関する情報を、フィールドとメソッドの説明とともに提供します。このページの情報は、APIを使う開発者ではなく、再実装を行う開発者に必要な情報です。直列化された形式ページへアクセスするには、直列化されたクラスに移動して、そのクラス・コメントにある「関連項目」セクションで「直列化された形式」をクリックします。標準ドックレットは直列化された形式ページを生成します。このページには、Serializable
を実装するすべてのクラス(publicまたは非public)が、そのreadObject
やwriteObject
メソッド、直列化されたフィールド、および@serial
、@serialField
、@serialData
タグからのドキュメンテーション・コメントとともにリストされます。publicのSerializable
クラスを除外するには、そのクラスまたはそのクラスが属するパッケージを@serial exclude
タグで指定します。package-privateのSerializable
クラスを含めるには、そのクラスまたはそのクラスが属するパッケージを@serial includeタ
グで指定します。-private
オプションの指定なしでjavadoc
コマンドを実行することにより、publicクラスおよびprivateクラスの完全に直列化された形式を生成できます。Javadocドックレットのオプションを参照してください。 -
索引ページ(
index-*.html
)。すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名が、アルファベット順に並んでいます。索引ページは、Unicodeを扱えるように国際化されています。1つのファイルとして生成することも、先頭文字(英語の場合A–Z)ごとに別々のファイルとして生成することもできます。
-
- サポート・ページ
-
-
ヘルプ・ページ(
help-doc.html
)。ナビゲーション・バーや前述の各ページに関する説明が記載されています。-helpfile
を使うと、デフォルトのヘルプ・ファイルを独自のカスタム・ヘルプ・ファイルでオーバーライドできます。 -
表示用のHTMLフレームを作成する1つの
index.html
ファイル。このファイルは、フレーム付きの先頭ページを表示する場合にロードします。index.html
ファイルには、テキスト・コンテンツは含まれていません。 -
いくつかのフレーム・ファイル(
*-frame.html
)。パッケージ、クラス、およびインタフェースのリストが含まれています。フレーム・ファイルはHTMLフレームを表示します。 -
package-list
ファイル。-link
オプションおよび-linkoffline
オプションで使用されます。パッケージ・リスト・ファイルはテキスト・ファイルであり、リンクからはアクセスできません。 -
スタイルシート・ファイル(
stylesheet.css
)。生成されるページの一部の要素について色、フォント・ファミリ、フォント・サイズ、フォント・スタイル、および配置を制御します。 -
doc-files
ディレクトリ。宛先ディレクトリにコピーするイメージ、サンプル・コード、ソース・コードなどのファイルが格納されます。これらのファイルは、javadoc
コマンドによって処理されません。このディレクトリは、ソース・ツリーの中にある場合にのみ処理されます。
Javadocドックレットのオプションを参照してください。
-
HTMLフレーム
javadoc
コマンドは、コマンドに渡された値に応じて、最低限必要な数(2つまたは3つ)のフレームを作成します。単一のパッケージ名、または単一のパッケージに属するソース・ファイルを引数としてjavadoc
コマンドに渡した場合、パッケージの一覧は省略されます。かわりに、javadoc
コマンドは、左側の列にクラスの一覧を表示するフレームを1つ作成します。javadoc
コマンドに複数のパッケージ名を渡した場合は、概要ページ(overview-summary.html
)に加えて、すべてのパッケージを一覧表示する第3のフレームが作成されます。HTMLフレームはデフォルトで無効にされていますが、--frames
オプションにより有効にできます。フレームを省略するには、「フレームなし」リンクをクリックするか、overview-summary.html
ページからページ・セットを表示します。Javadocの検索機能により、画面スペースのナビゲートと保存がしやすくなります。
生成されるファイルの構造
生成されるクラス・ファイルおよびインタフェース・ファイルは、Javaソース・ファイルおよびクラス・ファイルと同じディレクトリ階層に編成されます。1つのサブパッケージにつき1つのディレクトリ、という構造になります。
LinuxおよびmacOS: たとえば、java.math.BigDecimal
クラスに対して生成されたドキュメントはjava/math/BigDecimal.html
に格納されます。
Windows: たとえば、java.math.BigDecimal
クラスに対して生成されたドキュメントはjava\math\BigDecimal.html
に格納されます。
生成先のディレクトリの名前がapidocs
だとすると、java.math
パッケージのファイル構造は下記のようになります。前述のように、frameという語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外のHTMLファイルは、すべて右側のフレームに表示されます。
ディレクトリは太字です。アスタリスク(*)は、javadoc
コマンドへの引数がパッケージ名ではなくソース・ファイル名である場合に省略されるファイルおよびディレクトリを示しています。引数がソース・ファイル名の場合は、空のパッケージ・リストが作成されます。doc-files
ディレクトリは、ソース・ツリー内に存在する場合にのみ、生成先に作成されます。
生成されるAPI宣言
javadoc
コマンドは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の最初に、そのAPI用の宣言を生成します。たとえば、Boolean
クラスの宣言は、次のようになります。
public final class Boolean
extends Object
implements Serializable
Boolean.valueOf
メソッドの宣言は、次のようになります。
public static Boolean valueOf(String s)
javadoc
コマンドは、修飾子public
、protected
、private
、abstract
、final
、static
、transient
、およびvolatile
を組み込むことができますが、synchronized
とnative
を組み込むことができません。synchronized
およびnative
修飾子は、実装の詳細と見なされているため、API仕様には含まれません。
synchronized
に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。たとえば、説明は次のようにできます。 A single enumeration cannot be used by multiple threads concurrently.
ドキュメントには、これらのセマンティクスを実現する方法を記述しないでください。たとえば、Hashtable
オプションはスレッドセーフである必要がありますが、「エクスポートされるすべてのメソッドを同期化してそれを実現する」のように指定する根拠はありません。より高度な並行性のために、内部的に同期化する権限を保有しておくことをお薦めします。
javadocコマンドの実行例
javadoc
コマンドは、パッケージ全体に対して実行することも、個々のソース・ファイルに対して実行することもできます。Java言語で記述されたプログラムからjavadoc
コマンドを呼び出すには、公開プログラム・インタフェースを使用します。
javadoc
コマンドのリリース番号を判別するには、javadoc -J-version
オプションを使用します。出力ストリームには標準ドックレットのリリース番号が含まれます。-quiet
オプションで無効にできます。
Java言語で記述されたプログラムからjavadoc
コマンドを呼び出すには、com.sun.tools.javadoc.Main
の公開プログラム・インタフェースを使用します(javadoc
コマンドはリエントラントです)。
次の手順では、標準HTMLドックレットを呼び出します。カスタム・ドックレットを呼び出すには、-doclet
および-docletpath
オプションを使用します。
簡単な例
javadoc
コマンドをパッケージ全体に対して、または個々のソース・ファイルに対して実行する簡単な例を次に示します。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。
LinuxおよびmacOS: 次の例では、ソース・ファイルは/home/src/java/awt/*.java
にあります。生成先ディレクトリは/home/html
です。
Windows: 次の例では、ソース・ファイルはC:\home\src\java\awt\*java
にあります。生成先ディレクトリはC:\home\html
です。
1つまたは複数のパッケージのドキュメント化: パッケージをドキュメント化するには、そのパッケージのソース・ファイルを、そのパッケージと同じ名前のディレクトリ内に格納する必要があります。
LinuxおよびmacOS:
-
パッケージ名が(
java.awt.color
のようにドットで区切られた)複数の識別子から構成されている場合、後続の各識別子が下位のサブディレクトリ(java/awt/color
など)に対応している必要があります。 -
1つのパッケージのための複数のソース・ファイルを、異なる場所にある2つのディレクトリ・ツリーに分けて格納することも可能です。ただし、その場合は、
-sourcepath
オプションによって、その両方の場所を指定しなければなりません。たとえば、src1/java/awt/color
とsrc2/java/awt/color
です。
Windows:
-
パッケージ名が(
java.awt.color
のようにドットで区切られた)複数の識別子から構成されている場合、後続の各識別子が下位のサブディレクトリ(java\awt\color
など)に対応している必要があります。 -
1つのパッケージのための複数のソース・ファイルを、異なる場所にある2つのディレクトリ・ツリーに分けて格納することも可能です。ただし、その場合は、
-sourcepath
オプションによって、その両方の場所を指定しなければなりません。たとえば、src1\java\awt\color
とsrc2\java\awt\color
です。
javadoc
コマンドを実行するには、cd
コマンドを使ってディレクトリを変更するか、または-sourcepath
オプションを使用します。次の例では、両方の方法について説明します。
- 例1 1つ以上のパッケージから再帰的に実行
-
この例では、
javadoc
コマンドを再帰的処理のために任意のディレクトリから実行できるように-sourcepath
を使用します。これは、Javaディレクトリのサブパッケージをたどりますが、java.net
とjava.lang
をルートに持つパッケージは除外されます。java.lang
のサブパッケージであるjava.lang.ref
は除外されることに注意してください。その他のパッケージ・ツリーを巡回するには、java:javax:org.xml.sax
のように、-subpackages
引数にその名前を追加します。javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude
- 例2 ルートに移ってから明示的なパッケージに対して実行
-
-
完全修飾のパッケージ名の親ディレクトリに移ります。
-
ドキュメント化する1つ以上のパッケージの名前を指定して
javadoc
コマンドを実行します。LinuxおよびmacOS:
cd /home/src/ javadoc -d /home/html java.awt java.awt.event
Windows:
cd C:\home\src\ javadoc -d C:\home\html java.awt java.awt.event
その他のパッケージ・ツリーを巡回するには、
java:javax:org.xml.sax
のように、-subpackages
引数にその名前を追加します。
-
- 例3 1つのツリーにある明示的なパッケージに対して任意のディレクトリから実行
-
この場合、現在のディレクトリがどこかは問題ではありません。最上位パッケージの親ディレクトリを
-sourcepath
オプションに指定して、javadoc
コマンドを実行します。ドキュメント化する1つ以上のパッケージの名前を指定します。LinuxおよびmacOS:
javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
Windows:
javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event
- 例4 複数のツリーにある明示的なパッケージに対して任意のディレクトリから実行
-
各ツリーのルートへのパスをコロンで区切ったリストを
-sourcepath
オプションに指定して、javadoc
コマンドを実行します。ドキュメント化する1つ以上のパッケージの名前を指定します。指定したパッケージのすべてのソース・ファイルが、1つのルート・ディレクトリの下に存在する必要はありませんが、ソース・パスで指定された場所のどこかで見つかる必要があります。LinuxおよびmacOS:
javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event
Windows:
javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.event
結果として、上記のどのケースでも、パッケージ
java.awt
とjava.awt.event
のpublic
およびprotected
のクラスとインタフェースについて、HTML形式のドキュメントが生成され、指定された生成先ディレクトリにHTMLファイルが保存されます。2つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラス・ページという3つのHTMLフレームを持つことになります。
1つ以上のクラスのドキュメント化
1つ以上のソース・ファイルを渡してjavadoc
コマンドを実行することもできます。javadoc
は、次のどちらかの方法で実行できます。1つは、cd
コマンドでディレクトリを変更する方法、もう1つは、ソース・ファイルへのパスを完全指定する方法です。相対パスは、現在のディレクトリを起点とします。ソース・ファイルを渡すときは、-sourcepath
オプションは無視されます。アスタリスク(*)のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。
- 例1 ソース・ディレクトリに移る
-
ソース・ファイルのあるディレクトリに移ります。次に、ドキュメント化する1つ以上のソース・ファイルの名前を指定して
javadoc
コマンドを実行します。この例では、クラス
Button
とCanvas
、および名前がGraphics
で始まるクラスについて、HTML形式のドキュメントが生成されます。パッケージ名ではなくソース・ファイルがjavadoc
コマンドに引数として渡されているので、ドキュメントは、クラスのリストとメイン・ページという2つのフレームを持つことになります。LinuxおよびmacOS:
cd /home/src/java/awt javadoc -d /home/html Button.java Canvas.java Graphics*.java
Windows:
cd C:\home\src\java\awt javadoc -d C:\home\html Button.java Canvas.java Graphics*.java
- 例2 パッケージのルート・ディレクトリに移る
-
これは、同じルート内にある複数のサブパッケージの個々のソース・ファイルをドキュメント化する場合に便利です。パッケージのルート・ディレクトリに移り、各ソース・ファイルを、ルートからのパスとともに指定します。
LinuxおよびmacOS:
cd /home/src/ javadoc -d /home/html java/awt/Button.java java/math/BigDecimal.java
Windows:
cd C:\home\src javadoc -d \home\html java\awt\Button.java java\math\BigDecimal.java
- 例3 任意のディレクトリからファイルをドキュメント化する
-
この場合、現在のディレクトリがどこかは問題ではありません。ドキュメント化するソース・ファイルへの絶対パス(または、現在のディレクトリからの相対パス)を指定して
javadoc
コマンドを実行します。LinuxおよびmacOS:
javadoc -d /home/html /home/src/java/awt/Button.java \ /home/src/java/awt/Graphics*.java
Windows:
javadoc -d C:\home\html C:\home\src\java\awt\Button.java ^ C:\home\src\java\awt\Graphics*.java
パッケージとクラスのドキュメント化
パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に、前述の2つの例を組み合せた例を示します。-sourcepath
オプションは、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。
注意
-
-windowtitle
オプションを省略すると、javadoc
コマンドによって、ドキュメント・タイトルがウィンドウ・タイトルにコピーされます。-windowtitle
オプションのテキストは、-doctitle
オプションに似ていますが、HTMLタグは使用しません。HTMLタグは、ウィンドウ・タイトルにそのまま文字で(プレーン・テキストで)表示されてしまいます。 -
-footer
オプションを省略すると、javadoc
コマンドによって、ヘッダー・テキストがフッターにコピーされます。 -
前の例では必要ありませんでしたが、
-classpath
および-link
も重要なオプションです。 -
javadoc
コマンドは、有効なクラス名を含んでいるファイルだけを読み取ります。javadoc
コマンドがファイルの内容を正しく読み取っていない場合は、クラス名が有効であることを確認してください。