2 ソース・ファイル
javadoc
ツールは、次に示す種類のソース・ファイルから出力結果を生成します。そのファイルは、クラスのJava言語ソース・ファイル(.java
)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の処理されないファイルです。
このトピックでは、ソース・ツリーにやはり存在する場合があるものの、ドキュメント化しないようにする必要があるソース・ファイルやテスト・ファイル、テンプレート・ファイルについて説明します。
- クラス・ソース・ファイル
-
各クラスのソース・ファイルには独自のドキュメント・コメントがある場合があります。
- 概要コメント・ファイル
-
ドキュメント化する各アプリケーションまたはパッケージ・セットは、独自の概要ドキュメンテーション・コメントを持つことができ、それは専用のソース・ファイルに保持されます。その内容は、
javadoc
ツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージ・セット全体に当てはまるドキュメントを記述します。このファイルに
overview.html
などの任意の名前を付け、任意の場所に置くことができます。通常はソース・ツリーの最上位に置きます。Oracle Solaris、LinuxおよびmacOS: たとえば、
java.math
パッケージのソース・ファイルが/home/user/src/java/math
ディレクトリに含まれている場合は、/home/user/src/overview.html
に概要コメント・ファイルを作成できます。Windows: たとえば、
java.math
パッケージのソース・ファイルがC:\user\src\java\math
ディレクトリに含まれている場合は、C:\user\src\overview.html
に概要コメント・ファイルを作成できます。異なるパッケージのセットに対して
javadoc
ツールを複数回実行する場合は、同じ1つのソース・ファイルのセットに対して複数の概要コメント・ファイルを作成できます。たとえば、内部ドキュメンテーション用に-private
オプションを指定してjavadoc
ツールを1回実行した後、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメント・ファイルの1文目で、そのドキュメンテーションを公開用または内部用として記述できます。概要コメント・ファイルの内容は、HTMLで記述された1つの大きなドキュメンテーション・コメントです。最初の文は、アプリケーションまたはパッケージ・セットに関するサマリーにしてください。
<body>
タグと最初の文の間にタイトルやその他のテキストを含めないようにします。インライン・タグ({@link}
タグなど)以外のすべてのタグは、主説明の後に置く必要があります。@see
タグを追加する場合は、完全修飾名を使用しなければなりません。javadoc
ツールの実行時に、-overview
オプションを使って概要コメント・ファイル名を指定します。このファイルは、パッケージ・コメント・ファイルと同じように処理されます。javadoc
ツールは次の処理を行います。-
<body>
タグと</body>
タグの間にあるすべての内容を処理のためにコピーします。 -
概要タグがあればすべて処理します。
-
生成した概要ページの最後に、処理したテキストを挿入します。
-
概要ページの先頭に、概要コメントの最初の文をコピーする
-
- 処理されないファイル
-
ソース・ファイルには、
javadoc
ツールによって生成先のディレクトリにコピーする任意のファイルを含めることができます。このようなファイルには、通常、グラフィック・ファイル、サンプルのJavaソースおよびクラス・ファイル、一般的なJavaソース・ファイルのドキュメンテーション・コメントの影響を受けない多くの内容を含む独立したHTMLファイルなどがあります。処理されないファイルを含めるには、それらを
doc-files
というディレクトリに置きます。doc-files
ディレクトリは、ソース・ファイルがある任意のパッケージ・ディレクトリの下に作成できます。doc-files
サブディレクトリは、パッケージごとに1つ用意できます。Oracle Solaris、LinuxおよびmacOS: たとえば、ボタンのイメージを
java.awt.Button
クラスのドキュメントに含める場合は、そのイメージ・ファイルを/home/user/src/java/awt/doc-files/
ディレクトリに置きます。doc-files
ディレクトリを/home/user/src/java/doc-files
に置かないでください。java
はパッケージではないからです。そこにソース・ファイルは入っていません。Windows: たとえば、ボタンのイメージを
java.awt.Button
クラスのドキュメントに含める場合は、そのイメージ・ファイルを\src\java\awt\doc-files
ディレクトリに置きます。doc-files
ディレクトリを\src\java\doc-files
に置くことはできません。java
はパッケージではないからです。そこにソース・ファイルは入っていません。処理されないファイルへのリンクは、すべてコードに記述する必要があります。これは、
javadoc
ツールがそれらのファイルを見ないからです。javadoc
ツールは、ディレクトリとそのすべての内容を生成先にコピーします。たとえば、Button.java
のドキュメンテーション・コメント内のリンクは、次のようになります。/** * <p> This button looks like this:</p> * <img src="doc-files/Button.gif"/> */
- テスト・ファイルおよびテンプレート・ファイル
-
ソース・ツリー内で、ソース・ファイルが置かれているディレクトリと同じディレクトリまたはそのサブディレクトリに、テスト・ファイルとテンプレート・ファイルを格納できます。テスト・ファイルとテンプレート・ファイルが処理されないようにするには、個々のソース・ファイル名を明示的に渡して
javadoc
ツールを実行します。テスト・ファイルは、有効でコンパイル可能なソース・ファイルです。テンプレート・ファイルは、有効でコンパイル可能なソース・ファイルではありませんが、多くの場合
.java
接尾辞を持っています。-
テスト・ファイル : 名前のないパッケージまたはソース・ファイルが入っているパッケージとは別のパッケージにテスト・ファイルを所属させるには、ソース・ファイルの下のサブディレクトリに無効な名前を付け、そこにテスト・ファイルを置きます。ソース・ファイルと同じディレクトリにテスト・ファイルを置き、コマンド行引数でそのパッケージ名を指定して
javadoc
ツールを呼び出すと、テスト・ファイルによって警告またはエラーが発生します。無効な名前のサブディレクトリにテスト・ファイルを置いた場合、そのテスト・ファイル・ディレクトリはスキップされ、エラーや警告は発生しません。たとえば、com.package1
のソース・ファイルのテスト・ファイルを追加する場合は、無効なパッケージ名を持つサブディレクトリに置きます。次のディレクトリ名はハイフンを含んでいるため無効です。-
Oracle Solaris、LinuxおよびmacOS:
com/package1/test-files/
-
Windows:
com\package1\test-files\
テスト・ファイルにドキュメンテーション・コメントが含まれている場合は、
com/package1/test-files/*.java
のようにワイルドカードでテスト・ソース・ファイル名を渡してjavadoc
ツールを別個に実行すると、テスト・ファイルのドキュメントを生成できます。 -
-
テンプレート・ファイル : ソース・ディレクトリにテンプレート・ファイルを置く場合、
javadoc
ツールの実行時にエラーが発生しないようにするには、このファイルに無効なファイル名(Buffer-Template.java
など)を付けます。こうすることで、処理されないようになります。javadoc
ツールは、.java
接尾辞を除いた名前が有効なクラス名であるソース・ファイルだけを処理します。
-
パッケージ・コメント・ファイルの処理
javadoc
ツールは、実行時にパッケージ・コメント・ファイルを検索します。パッケージ・コメント・ファイルが見つかった場合、javadoc
ツールは次の処理を行います。
-
処理できるようにコメントをコピーします。
package.html
の場合、javadoc
ツールは、<body>
と</body>
HTMLタグの間にある内容をすべてコピーします。<head>
セクションを含め、そこに<title>
タグやソース・ファイルの著作権記述などの情報を配置することもできますが、生成されたドキュメントにはそれらは一切表示されません。 -
パッケージ・タグを処理します。
-
生成したパッケージ・サマリー・ページの最後に、処理したテキストを挿入します。
-
パッケージのサマリー・ページの先頭に、パッケージ・コメントの最初の文をコピーする。さらに、
javadoc
ツールは、概要ページのパッケージ・リストに、パッケージ名とこの最初の文を追加します。文の末尾は、クラスやメンバーの主説明の最初の文の末尾に使用されるルールによって判断されます。