ソース・ファイル

2 ソース・ファイル

javadocツールは、次に示す種類のソース・ファイルから出力結果を生成します。そのファイルは、クラスのJava言語ソース・ファイル(.java)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の処理されないファイルです。

このトピックでは、ソース・ツリーにやはり存在する場合があるものの、ドキュメント化しないようにする必要があるソース・ファイルやテスト・ファイル、テンプレート・ファイルについて説明します。

クラス・ソース・ファイル

各クラスのソース・ファイルには独自のドキュメント・コメントがある場合があります。

概要コメント・ファイル

ドキュメント化する各アプリケーションまたはパッケージ・セットは、独自の概要ドキュメンテーション・コメントを持つことができ、それは専用のソース・ファイルに保持されます。その内容は、javadocツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージ・セット全体に当てはまるドキュメントを記述します。

このファイルにoverview.htmlなどの任意の名前を付け、任意の場所に置くことができます。通常はソース・ツリーの最上位に置きます。

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つ用意できます。

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のソース・ファイルのテスト・ファイルを追加する場合は、無効なパッケージ名を持つサブディレクトリに置きます。次のディレクトリ名はハイフンを含んでいるため無効です。
- 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ツールは、概要ページのパッケージ・リストに、パッケージ名とこの最初の文を追加します。

文の末尾は、クラスやメンバーの主説明の最初の文の末尾に使用されるルールによって判断されます。