javadoc.1 revision 1178
1178N/A." CA 95054 USA or visit www.sun.com if you need additional information or
1178N/AJava ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、Sun Solaris を使用した場合のものです。
1178N/A\f4javadoc\fP\f2\ [\ \fP\f2options\fP\f2\ ]\ [\ packagenames\ ]\ [\ sourcefilenames\ ]\ [\ \-subpackages\fP\ \f2pkg1:pkg2:...\fP\f2\ ]\ [\ \fP\f2@argfiles\fP\f2\ ]\fP
1178N/Aスペースで区切られた一連のパッケージ名です。 たとえば、\f2java.lang\ java.lang.reflect\ java.awt\fP のように指定します。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用不可です。 再帰的処理のためには、\-subpackages を使用します。Javadoc ツールは、\f2\-sourcepath\fP を使ってこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。
1178N/Aスペースで区切られた一連のソースファイル名です。各ファイルは、パスで始まります。アスタリスク (*) などのワイルドカードを含めることができます。 Javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (
1178N/Ahttp://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625を参照)。したがって、ハイフンを含む名前 (\f2X\-Buffer\fP など) や、その他の無効な文字を含む名前を付けることによって、それらのファイルをドキュメント化の対象から除外できます。これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。 ソースファイル名の前に指定したパスによって、javadoc がそのファイルを検索する場所が決まります。Javadoc ツールは、これらのソースファイル名を検索するときに \f2\-sourcepath\fP は使いません。相対パスは、現在のディレクトリからの相対パスです。 \f2Button.java\fP を渡すことは、\f2./Button.java\fP を渡すことと同じです。ソースファイル名をフルパスで指定すると、\f2/home/src/java/awt/Graphics*.java\fP のようになります。「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイル名を混在させることもできます。
1178N/AJavadoc オプション、パッケージ名、およびソースファイル名を任意の順序で並べたリストが含まれる 1 つ以上のファイルです。このファイルの中では、ワイルドカード (*) および \f2\-J\fP オプションは指定できません。
1178N/A\f3Javadoc\fP ツールは、一連の Java ソースファイルにある宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラス、protected クラス、入れ子にされたクラス (匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。
1178N/AJavadoc ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。javadoc ツールをパッケージ全体に対して実行する場合は、最上位ディレクトリから再帰的にたどるために \f2\-subpackages\fP を使用するか、パッケージ名の明示的なリストを渡します。個々ソースファイルに対して javadoc を実行する場合は、一連のソース (\f2.java\fP) ファイル名を渡します。具体的な例は、このドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。
1178N/AJavadoc ツールは、末尾に \f2.java\fP の付いたファイル以外に、ソースファイルで説明する他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、どの \f2.java\fP ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。 パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。この方法は、(1) パッケージ名を渡す、(2) \f2\-subpackages\fP を使用する、(3) ソースファイル名にワイルドカードを使用する (\f2*.java\fP) という方法です。これらの方法を使用する場合、Javadoc ツールは、\f2.java\fP ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。
1178N/A\f3リンクの処理\fP \- Javadoc ツールは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、自動的に相互参照リンクを追加します。このようなリンクは、次のような場所に追加されます。
1178N/Aコマンド行で指定しなかったクラスについての既存のテキスト (別に生成したテキスト) に対してハイパーリンクを追加するには、\f2\-link\fP および \f2\-linkoffline\fP オプションを利用できます。
1178N/A\f3その他の処理についての詳細\fP \- Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。 ドキュメントを追加生成することはできません。 つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加することはできます。
1178N/A実装上の理由から、Javadoc ツールは、処理を実行するために java コンパイラを必要とし、java コンパイラに依存しています。Javadoc ツールは \f2javac\fP の一部を呼び出すことにより、宣言をコンパイルし、メンバーの実装は無視します。Javadoc ツールは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、その情報から HTML を生成します。さらに、Javadoc ツールは、ソースコードのドキュメンテーションコメントから、ユーザーの提供したドキュメントも取得します。
1178N/AJavadoc ツールは、メソッド本体のない純粋なスタブファイルである \f2.java\fP ソースファイルに対しても、実行することができます。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。
1178N/Aコンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。 実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、Javadoc ツールは、\f2.class\fP ファイル内に存在するが、ソースコード内には存在しない
1178N/Ahttp://java.sun.com/docs/books/jls/second_edition/html/names.doc.html#36154 (Java 言語仕様のセクション 8.6.7) をドキュメント化します。
1178N/A通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。
1178N/AJavadoc ツールは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、Javadoc ツールは、ブートストラップクラス、拡張機能、またはユーザークラスにかかわらず、すべての参照クラスを検索できなければなりません。詳細は、
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/tools/findingclasses.htmlを参照してください。通常、作成するクラスは、拡張機能としてロードするか、Javadoc ツールのクラスパス内に置く必要があります。
1178N/AJavadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。 標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。
1178N/A\f2\-doclet\fP コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html \- Javadoc で追加された改良点の詳細
1178N/Ahttp://java.sun.com/j2se/javadoc/faq/index.html \- 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html \- ドキュメンテーションコメントの記述方法に関する Sun の規約
1178N/Ahttp://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Java 2 プラットフォーム仕様を記述する際に使用された標準要件。この情報は、ソースファイルのドキュメンテーションコメント形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも役立ちます。検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールド、およびメソッドについての要件を定めています。
1178N/Ahttp://java.sun.com/docs/books/jls/first_edition/html/18.doc.html \- ドキュメンテーションコメントのオリジナル仕様については、『Java Language Specification』 (James Gosling、Bill Joy、Guy Steele 共著) の初版の第 18 章「Documentation Comments」を参照してください。この章は、第 2 版では削除されました。
1178N/Ahttp://java.sun.com/javadoc/doccheck \- ソースファイル内のドキュメンテーションコメントをチェックし、検出されたエラーや不正のレポートを生成します。Sun Doc Check ユーティリティーの一部です。Sun Doc Check ユーティリティーの一部です。
1178N/Ahttp://java.sun.com/javadoc/mifdoclet \- MIF、FrameMaker、PDF の書式で API ドキュメントを自動生成します。MIF は Adobe FrameMaker の交換書式です。
1178N/A\f2「ドキュメンテーションコメント」\fP、\f2「doc コメント」\fP、\f2「主説明」\fP、\f2「タグ」\fP、\f2「ブロックタグ」\fP、および\f2「インラインタグ」\fPの用語については、「ドキュメンテーションコメント」で説明します。次のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。
1178N/Ajavadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。
1178N/AJava 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、\f2java.lang.String.equals(java.lang.Object)\fP のように完全修飾することも、\f2equals(Object)\fP のように部分修飾することもできます。
1178N/Ajavadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名を javadoc コマンドに渡され、アクセス修飾子 (public、protected、package\-private または private) によってフィルタ処理されないようにしなければなりません。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。
1178N/Aドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、{@linkplain}、{@inheritDoc} タグなどがあります。この定義は
1178N/Ahttp://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリーにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つかりません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバーの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。
1178N/A参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、\f2java.awt\fP パッケージに対してだけ Javadoc ツールを実行した場合、\f2Object\fP などの \f2java.lang\fP 内のすべてのクラスが外部参照クラスになります。外部参照クラスにリンクするには、\f2\-link\fP および \f2\-linkoffline\fP オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継承することはできません。
1178N/AJavadoc ツールは、4 種類の異なるソースファイルから出力結果を生成します。そのファイルは、クラスの Java 言語ソースファイル (\f2.java\fP)、パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルです。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートファイルについても説明します。
1178N/Aそれぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーションコメントを持つことができ、それを \f2.java\fP ファイル内に保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテーションコメント」を参照してください。
1178N/Aそれぞれのパッケージは、独自のドキュメンテーションコメントを持つことができ、それを専用の「ソース」ファイルに保持します。 その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。
1178N/A\f2package\-info.java\fP \- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは JDK 5.0 で導入されたものであり、package.html よりも推奨されています。
1178N/A\f2package.html\fP \- 格納できるのはパッケージコメントと Javadoc タグだけです。 パッケージ注釈は格納できません。
1178N/A各パッケージは、単一の \f2package.html\fP ファイル、単一の \f2package\-info.java\fP ファイルのいずれかを持つことができますが、両方を持つことはできません。このどちらかのファイルを \f2.java\fP ファイルとともに、ソースツリー内のそのパッケージのディレクトリ内に配置してください。
1178N/A\f4package\-info.java\fP \- このファイルには、次の構造のパッケージコメントを格納できます。 コメントはパッケージ宣言の前に配置します。
0N/A * {@link java.awt.Panel} class) with a few extra
0N/Apackage java.lang.applet;
1178N/A\f4package.html\fP \- このファイルには、次の構造のパッケージコメントを格納できます。 コメントは \f2<body>\fP 要素内に配置します。
1178N/AFile:\f2java/applet/package.html\fP
0N/Awindow (see the {@link java.awt.Panel} class) with a
1178N/Aこれは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述されています。それは、このドキュメンテーションコメントには、コメント区切り文字である \f2/**\fP と \f2*/\fP、および行頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージの概要とし、\f2<body>\fP と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、すべてのブロックタグは、主説明のあとに置かなければなりません。パッケージコメントファイルに \f2@see\fP タグを追加する場合は、完全指定の名前を使用する必要があります。詳細は、
1178N/A\f2package.html\fP の例 @
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#packagecommentsを参照してください。
1178N/A処理できるようにコメントをコピーする (\f2package.html\fP の場合であれば、\f2<body>\fP と \f2</body>\fP HTML タグの間にある内容をすべてコピーする。\f2<head>\fP を含め、そこに \f2<title>\fP やソースファイルの著作権記述などの情報を配置することもできるが、生成後のドキュメンテーションにはそれらは一切表示されない)
1178N/Ahttp://java.sun.com/javase/6/docs/api/overview\-summary.html)。文の末尾は、クラスやメンバーの主説明の最初の文の末尾と同じ規則によって判断される
1178N/Aドキュメント化する各アプリケーションまたはパッケージセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは専用の「ソース」ファイルに保持されます。 その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージセット全体に当てはまるドキュメントを記述します。
1178N/A概要コメントファイルを作成する場合は、ファイルに任意の名前を付け、任意の場所に置くことができます。ただし、通常は、ファイル名を \f4overview.html\fP にして、ソースツリーの最上位レベルに置きます。たとえば、\f2java.applet\fP パッケージのソースファイルが \f2/home/user/src/java/applet\fP ディレクトリに含まれている場合は、\f2/home/user/src/overview.html\fP に概要コメントファイルを作成できます。
1178N/A異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。たとえば、内部ドキュメンテーション用に \-private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。
1178N/A概要コメントファイルの内容は、前述のパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。詳細は、前述の説明を参照してください。要点を繰り返すと、このコメントを記述する場合は、最初の文をアプリケーションまたはパッケージセットの要約とし、\f2<body>\fP と最初の文の間にタイトルその他のテキストを含めないようにします。概要タグを含めることができます。 どのドキュメンテーションコメントについても、インラインタグ (\f2{@link}\fP など) 以外のすべてのタグは、主説明のあとに置く必要があります。\f2@see\fP タグを追加する場合は、完全指定の名前を使用しなければなりません。
1178N/Aソースには、Javadoc ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファイル、サンプルの Java ソース (.java) およびクラス (.class) ファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。
1178N/A未処理のファイルをソースに含めるには、それらのファイルを \f4doc\-files\fP というディレクトリに置きます。 このディレクトリは、ソースファイルがある任意のパッケージディレクトリの下に作成できます。このようなサブディレクトリは、パッケージごとに 1 つ用意できます。イメージ、サンプルコード、ソースファイル、.class ファイル、アプレット、および HTML ファイルをこのディレクトリに格納できます。たとえば、ボタンのイメージ \f2button.gif\fP を \f2java.awt.Button\fP クラスのドキュメントに含める場合は、そのファイルを \f2/home/user/src/java/awt/doc\-files/\fP ディレクトリに置きます。\f2doc\-files\fP ディレクトリを \f2/home/user/src/java/doc\-files\fP に置くことはできません。 これは、\f2java\fP はパッケージではなく、そのディレクトリそのものにソースファイルが入っていないからです。
1178N/Aこれらの未処理のファイルへのリンクは、すべて明示的に記述する必要があります。 これは、Javadoc ツールがそれらのファイルを見ずに、単にディレクトリとその内容を生成先にコピーするだけだからです。たとえば、\f2Button.java\fP のドキュメンテーションコメント内のリンクは、次のようになります。
1178N/A * <img src="doc\-files/Button.gif">
1178N/A一部の開発者から、テストファイルおよびテンプレートファイルを対応するソースファイルの近くのソースツリーに保存したいという要望がありました。つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに保存したいということです。
1178N/A個別のソースファイル名で明示的に渡して Javadoc ツールを実行する場合は、テストファイルおよびテンプレートファイルを意図的に除外して、処理されないようにすることができます。ただし、パッケージ名またはワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイルおよびテンプレートファイルが処理されないようにする必要があります。
1178N/Aテストファイルとテンプレートファイルの違いは、テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、テンプレートファイルは、そうではないという点です。 ただし、テンプレートファイルも「.java」で終わることができます。
1178N/A\f3テストファイル\fP \- 開発者の多くは、あるパッケージのコンパイル可能で実行可能なテストファイルをそのパッケージのソースファイルと同じディレクトリに配置したいと考えています。しかしテストファイルは、名前なしパッケージなど、ソースファイルパッケージとは別のパッケージに属させたいとも考えています (そのため、テストファイルには package ステートメントがないか、またはソースとは別の package ステートメントがある)。このような状況では、コマンド行で指定されているソースのパッケージ名を指定してそのソースがドキュメント化されているときに、テストファイルは警告またはエラーを引き起こします。そのようなテストファイルはサブディレクトリに配置する必要があります。\f2com.package1\fP に追加する場合は、それらのテストファイルを、ハイフンが含まれるためパッケージ名としては無効になるサブディレクトリに配置します。
1178N/A com/package1/test\-files/
1178N/Aテストファイルに doc コメントが含まれる場合、次のようにワイルドカードを含んだテストソースファイル名で渡してテストファイルのドキュメントを生成するように、Javadoc ツールを別個に実行できるように設定できます。 たとえば、\f2com/package1/test\-files/*.java\fP などです。
1178N/A\f3ソースファイルのテンプレート\fP \- テンプレートファイルの名前は「.java」で終わることもありますが、テンプレートファイルはコンパイルできません。ソースディレクトリに保持したいソースファイルのテンプレートがある場合は、このファイル名にハイフン (\f2Buffer\-Template.java\fP など) やその他の不正な Java 文字を使用します。 こうすることで、処理されないようになります。これは、Javadoc ツールが処理するのは、「.java」接尾辞を除いた名前が 正規のクラス名であるソースファイルだけであるためです (
1178N/Aデフォルトでは、javadoc ツールは、HTML 形式のドキュメントを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。 それぞれの HTML ページは、個々のファイルに相当します。javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの (\f2package\-summary.html\fP など) の 2 種類があります。後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。
1178N/Aドキュメント化するパッケージごとに 1 つの\f3パッケージページ\fP (\f2package\-summary.html\fP)。Javadoc ツールは、ソースツリーのパッケージディレクトリ内に \f2package.html\fP または \f2package\-info.java\fP というファイルがあれば、その中の HTML テキストをこのページに組み入れます。
1178N/Aパッケージセット全体に対して 1 つの\f3概要ページ\fP (\f2overview\-summary.html\fP)。これは、生成ドキュメントの先頭ページになります。Javadoc ツールは、\f2\-overview\fP オプションで指定されたファイル内の HTML テキストをこのページに組み入れます。このページのファイルは、javadoc に複数のパッケージ名を渡した場合にだけ作成されます。詳細は、「HTML フレーム」を参照してください。
1178N/A\f3パッケージのセット全体に対して 1 つのクラス階層ページ\fP (\f2overview\-tree.html\fP)。このページを表示するには、ナビゲーションバーの [概要] をクリックしてから、[階層ツリー] をクリックします。
1178N/A\f3パッケージごとに 1 つのクラス階層ページ\fP (\f2package\-tree.html\fP)。 特定のパッケージ、クラス、またはインタフェースのページを表示してから、[階層ツリー] をクリックすると、そのパッケージのクラス階層が表示されます。
1178N/A\f3パッケージごとに 1 つの [使用] ページ\fP (\f2package\-use.html\fP)と、\f3クラスおよびインタフェースごとに 1 つずつの [使用] ページ\fP (\f2class\-use/\fP\f2クラス名\fP\f2.html\fP)。このページには、特定のクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。クラスまたはインタフェース A を例にして考えると、その [使用] ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示されます。 このページを表示するには、まず、パッケージ、クラス、またはインタフェースのページに移動してから、ナビゲーションバーの [使用] リンクをクリックします。
1178N/A\f3非推奨 API ページ\fP (\f2deprecated\-list.html\fP)。 推奨されないすべての名前が一覧表示されます。非推奨名は、一般に改良された API が存在するために使用が推奨されていない API の名前であり、通常、それに置き換わる名前が提示されています。非推奨 API は、将来の実装では削除される可能性があります。
1178N/A\f3定数フィールド値ページ\fP (\f2constant\-values.html\fP)。 static フィールドの値用です。
1178N/A\f3直列化されたフォームページ\fP (\f2serialized\-form.html\fP)。 直列化および外部化可能なクラスです。これらの各クラスには、直列化フィールドおよびメソッドに関する説明があります。これらの情報は、API を使う開発者ではなく、再実装を行う開発者に必要な情報です。ナビゲーションバーにこのページへのリンクはありませんが、直列化されたクラスに移動して、そのクラスの説明にある [関連項目] セクションで [直列化された形式] をクリックすると、この情報を取得できます。標準ドックレットは、直列化された形式のページを自動的に生成します。ここには、Serializable を実装する public または非 public のクラスが組み込まれており、さらに、\f2readObject\fP メソッド、\f2writeObject\fP メソッド、直列化されたフィールド、および \f2@serial\fP タグ、\f2@serialField\fP タグ、\f2@serialData\fP タグからのドキュメンテーションコメントが組み込まれています。直列化が可能な public クラスを除外するには、そのクラスまたはそのクラスが属するパッケージを \f2@serial exclude\fP タグで指定します。 直列化が可能な package private クラスを含めるには、そのクラスまたはそのクラスが属するパッケージを \f2@serial include\fP タグで指定します。バージョン 1.4 では、\f2\-private\fP オプションの指定なしで javadoc ツールを実行することにより、public クラスおよび private クラスの完全に直列化されたクラスを生成できます。
1178N/A\f3索引\fP (\f2index\-*.html\fP)。 すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名が、アルファベット順に並んでいます。索引は、Unicode を扱えるように国際化されています。 1 つのファイルとして生成することも、先頭文字 (英語の場合 A 〜 Z) ごとに別々のファイルとして生成することもできます。
1178N/A\f3ヘルプページ\fP (\f2help\-doc.html\fP)。 ナビゲーションバーや前述の各ページに関する説明が記載されています。\f2\-helpfile\fP を使うと、デフォルトのヘルプファイルに代わる独自のカスタムヘルプファイルを提供することもできます。
1178N/A表示用の HTML フレームを作成する 1 つの \f3index.html ファイル\fP。このファイルは、フレーム付きの先頭ページを表示する場合にロードします。このファイル自体には、テキスト内容は含まれていません。
1178N/A複数の\f3フレームファイル\fP (\f2*\-frame.html\fP)。 パッケージ、クラス、およびインタフェースのリストが含まれています。 HTML フレームを表示するときに使用されます。
1178N/A\f3パッケージリスト\fPファイル (\f2package\-list\fP)。 \f2\-link\fP オプションおよび \f2\-linkoffline\fP オプションで使用されます。これは、HTML ファイルではなくテキストファイルであり、どのリンクからもアクセスできません。
1178N/A\f3スタイルシート\fPファイル (\f2stylesheet.css\fP)。 生成されるページ上のいくつかの要素について、色、フォントファミリ、フォントサイズ、フォントのスタイル、および配置を制御します。
1178N/A\f3doc\-files\fP ディレクトリ。 生成先ディレクトリにコピーするイメージ、サンプルコード、ソースコードなどのファイルがすべて格納されます。これらのファイルは、Javadoc ツールによって処理されないため、ファイル内に javadoc タグがあっても無視されます。このディレクトリは、ソースツリーの中にある場合にのみ生成されます。
1178N/AJavadoc ツールは、下の図に示すように、2 〜 3 つの HTML フレームを生成します。1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。単一のパッケージに属するソースファイル (*.java) または単一のパッケージ名を引数として javadoc コマンドに渡す場合は、左側の列にクラスの一覧を表示するフレーム (C) 1 つだけが作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、\f2overview\-summary.html\fP です。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。[フレームなし] リンクをクリックするか、overview\-summary.html を最初に表示すると、フレームを省略できます。
1178N/AHTML フレームに慣れていない場合は、特定のフレームを印刷およびスクロールするには、そのフレームに「フォーカス」がなければならないことに注意してください。フレームにフォーカスを与えるには、そのフレームをクリックします。このようにすると、多くのブラウザでは、矢印キーやページキーを使ってそのフレームをスクロールしたり、[印刷] メニューコマンドを使ってそのフレームを印刷したりできます。
1178N/A\f2index.html\fP (フレームあり)
1178N/A\f2overview\-summary.html\fP (フレームなし)
1178N/A生成されるクラスファイルおよびインタフェースファイルは、Java ソースファイルおよびクラスファイルと同じディレクトリ階層に編成されます。1 つのサブパッケージにつき 1 つのディレクトリ、という構造になります。
1178N/Aたとえば、\f2java.applet.Applet\fP クラスに対して生成されるドキュメントは、\f2java/applet/Applet.html\fP に格納されます。生成先のディレクトリの名前が \f2apidocs\fP だとすると、java.applet パッケージのファイル構造は、その下に構築されます。前述のように、「frame」という語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外の HTML ファイルは、すべて右側のフレームに表示されます。
1178N/A注 \- 下の階層図で、ディレクトリは\f3太字\fP (\f3bold\fP) で示してあります。アスタリスク (\f2*\fP) は、javadoc への引数がパッケージ名ではなくソースファイル名 (*.java) である場合に省略されるファイルおよびディレクトリを示しています。また、引数がソースファイル名の場合は、\f2package\-list\fP は作成されますが、内容は空です。doc\-files ディレクトリは、ソースツリー内に存在する場合にのみ、生成先に作成されます。
1178N/A index.html HTML フレームを設定する初期ページ
1178N/A * overview\-summary.html 全パッケージのリスト。 先頭に要約文がある
1178N/A overview\-tree.html 全パッケージのクラス階層のリスト
1178N/A deprecated\-list.html 全パッケージの推奨されない API のリスト
1178N/A constant\-values.html 全パッケージの static フィールドの値のリスト
1178N/A serialized\-form.html 全パッケージの直列化された形式のリスト
1178N/A * overview\-frame.html 全パッケージのリスト。 左上のフレームに表示される
1178N/A allclasses\-frame.html 全パッケージの全クラスのリスト。 左下のフレームに表示される
1178N/A stylesheet.css フォント、色、配置を定義する HTML スタイルシート
1178N/A Applet.html Applet クラスのページ
1178N/A AppletContext.html AppletContext インタフェースのページ
1178N/A AppletStub.html AppletStub インタフェースのページ
1178N/A AudioClip.html AudioClip インタフェースのページ
1178N/A * package\-summary.html このパッケージのクラスのリスト。 先頭に要約文がある
1178N/A * package\-frame.html このパッケージのクラスのリスト。 左下のフレームに表示される
1178N/A * package\-tree.html このパッケージのクラス階層のリスト
1178N/A Applet.html Applet クラスを使用するページ
1178N/A AppletContext.html AppletContext インタフェースを使用するページ
1178N/A AppletStub.html AppletStub インタフェースを使用するページ
1178N/A AudioClip.html AudioClip インタフェースを使用するページ
1178N/A Applet.html Applet ソースコードのページ
1178N/A AppletContext.html AppletContext ソースコードのページ
1178N/A AppletStub.html AppletStub ソースコードのページ
1178N/A AudioClip.html AudioClip ソースコードのページ
1178N/AJavadoc ツールは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の最初に、その API 用の宣言を生成します。 この宣言は、その API 項目の宣言です。たとえば、\f2Boolean\fP クラスの宣言は、次のようになります。
1178N/Aまた、\f2Boolean.valueOf\fP メソッドの宣言は、次のようになります。
1178N/AJavadoc ツールは、修飾子 \f2public\fP、\f2protected\fP、\f2private\fP、\f2abstract\fP、\f2final\fP、\f2static\fP、\f2transient\fP、および \f2volatile\fP を組み込むことができますが、\f2synchronized\fP と \f2native\fP を組み込むことができません。これら後者の 2 つの修飾子は、実装の詳細と見なされているため、API 仕様には含まれません。
1178N/AAPI では、並行性のセマンティクスについて、キーワード \f2synchronized\fP に依存するのではなく、コメントによる主説明としてドキュメント化する必要があります。 たとえば、「1 つの \f2Enumeration\fP を複数のスレッドから並行して使用することはできない」などのコメントを記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述するべきではありません。たとえば、\f2Hashtable\fP はスレッドに対して安全である必要がありますが、「エクスポートされるすべてのメソッドを同期化すればそれを実現できる」のようには指定する根拠はありません。バケットレベルで内部的に同期化する権利を残しておく必要があります。 そうすれば、より高度な並行性が提供されます。
1178N/Aソースコードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーションコメント ("doc comments") を記述することができます。各パッケージにドキュメンテーションコメントを作成できます。 構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。ドキュメンテーションコメントは、非公式に「Javadoc コメント」と呼ばれています (この用語は商標関連の使用法に違反)。ドキュメンテーションコメントは、コメントの始まりを示す文字列 \f2/**\fP と、コメントの終わりを示す文字列 \f2*/\fP の間にある文字で構成されます。行の先頭のアスタリスクは、各行に記述できます。 詳細は、以下で説明します。コメントのテキストは、複数行にわたって記述できます。
1178N/A\f3コメントの配置\fP \- ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。 クラスの例、メソッドの例、およびフィールドの例を参照してください。メソッドの本体に置かれているドキュメンテーションコメントは無視されます。javadoc ツールでは、1 つの宣言文につき 1 つのドキュメンテーションコメントだけが認識されます。
1178N/A\f3ドキュメンテーションコメントは主説明のあとにタグセクションが続く\fP \- コメントの開始区切り文字である \f2/**\fP のあとからタグセクションまでが主説明になります。タグセクションは、先頭文字が \f2@\fP である行で定義される最初のブロックタグから始まります (行の先頭のアスタリスク、空白、および行の先頭の区切り文字 \f2/**\fP は除く)。主説明を記述せず、タグセクションだけのコメントを記述することもできます。主説明は、タグセクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。 何回も記述できるタグと、1 回しか記述できないタグがあります。例えば、次の \f2@see\fP からタグセクションが始まります。
0N/A * @see java.lang.Object
1178N/A\f3ブロックタグとインラインタグ\fP \- 「タグ」は、Javadoc が処理できる、ドキュメンテーションコメント内の特別なキーワードです。\f2@tag\fP のように記述するブロックタグ (「スタンドアロンタグ」とも呼ばれる) と、インラインタグ (\f2{@tag}\fP のように中括弧で囲んで記述) の 2 種類のタグがあります。ブロックタグが正しく解釈されるためには、行の先頭のアスタリスク、空白、区切り文字 (\f2/**\fP) を除いて、行の先頭に置かなければなりません。これは、テキスト内のそれ以外の位置で \f2@\fP 文字を使用しても、タグの開始としては解釈されないことを意味しています。行の最初に \f2@\fP 文字を使用してもタグとして解釈されないようにするには、HTML エンティティーの「\f2@\fP」を使用してください。それぞれのブロックタグには、対応付けられたテキストがあります。 このテキストは、タグのあとから、次のタグの前、またはドキュメンテーションコメントの最後までの間に記述されたテキスト (タグやコメント区切り文字を除く) です。この関連テキストは複数行にわたって記述できます。インラインタグは、テキストを記述できる場所であればどこにでも置くことができ、正しく解釈されます。次のコード例には、ブロックタグ \f2@deprecated\fP と、インラインタグ \f2{@link}\fP が含まれています。
1178N/A\f3コメントは HTML で記述する\fP \- テキストは HTML 形式で記述しなければなりません。 これは、HTML のエンティティーを使う必要があること、および HTML タグを使用できることを意味します。記述する HTML のバージョンとしては、使用するブラウザがサポートする任意のバージョンを使用できます。 標準ドックレットは、カスケーディングスタイルシート (CSS) とフレームを含め、すべての部分 (ドキュメンテーションコメント以外の部分) で HTML 3.2 に準拠したコードを生成するように作成されています。ただし、フレームセット対応のため、生成される各ファイルには「HTML 4.0」と記述されます。
1178N/Aたとえば、より小さい (\f2<\fP) およびより大きい (\f2>\fP) という記号は\f2<\fP および \f2>\fP として記述する必要があります。同様に、アンパサンド (\f2&\fP) は、\f2&\fP と記述する必要があります。次の例では、ボールドの HTML タグ \f2<b>\fP を使っています。
1178N/A * @see java.lang.Object
1178N/A\f3行頭のアスタリスク\fP \- Javadoc は、ドキュメンテーションコメントを解析するときに、各行の先頭にあるアスタリスク (\f2*\fP) をすべて破棄します。 また、最初のアスタリスク (\f2*\fP) より前の空白とタブも破棄します。バージョン 1.4 からは、行の先頭のアスタリスクを省略しても、先頭の空白文字は削除されなくなりました。このため、コード例を直接ドキュメンテーションコメントの \f2<PRE>\fP タグ内にペーストしても、インデントが保持されます。通常、ブラウザは、空白文字をタブよりも一律に解釈します。インデントは区切り文字 \f2/**\fP または \f2<PRE>\fP タグよりも左寄りになります。
1178N/A\f3最初の文\fP \- 各ドキュメンテーションコメントの最初の文は、宣言されているエンティティーに関する簡潔かつ完全な要約文である必要があります。この「最初の文」は、直後にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のタグがある位置で終わります。最初の文は、Javadoc ツールによって HTML ページの最初にあるメンバーの概要の部分にコピーされます。
1178N/A\f3複数フィールドの宣言\fP \- Java では、1 つの文で複数のフィールドを宣言できます。 ただし、この文には、1 つのドキュメンテーションコメントしか記述できません。 そのコメントが、すべてのフィールドに対してコピーされます。したがって、フィールドごとにドキュメンテーションコメントを記述する必要がある場合は、各フィールドを別々の文で宣言しなければなりません。たとえば、次のドキュメンテーションコメントは、1 つの宣言として記述すると不適切です。 この場合は、宣言を 2 つに分けることをお勧めします。
1178N/A\f3見出しタグはなるべく使用しない\fP \- メンバーに対してドキュメンテーションコメントを記述するときには、<H1> や <H2> などの HTML 見出しタグは、なるべく使わないでください。 Javadoc ツールは、完全に構造化されたドキュメントを作成するので、このような構造化タグが使われていると、生成ドキュメントの形式が悪影響を受けることがあります。ただし、クラスやパッケージのコメントでは、これらの見出しタグを使って独自の構造を組み立ててかまいません。
1178N/AJavadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。
1178N/A\f3自動的にコメントを継承して、見つからないテキストを埋める\fP \- 主説明、または \f2@return\fP タグ、\f2@param\fP タグ、\f2@throws\fP タグが、メソッドコメントで見つからない場合、Javadoc ツールは、オーバーライドしたメソッドまたは実装している場合はそのメソッドから、対応する主説明またはタグコメントを、次のアルゴリズムに従ってコピーします。
1178N/A厳密には、特定のパラメータの \f2@param\fP タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の \f2@throws\fP タグが見つからない場合、その例外が宣言されている場合にかぎり、その \f2@throws\fP タグがコピーされます。
1178N/A\f3{@inheritDoc} タグを持つコメントを明示的に継承する\fP \- インラインタグ \f2{@inheritDoc}\fP を、メソッドの主説明、または \f2@return\fP、\f2@param\fP、\f2@throws\fP タグコメントに挿入します。 継承した対応する主説明またはタグコメントは、その箇所にコピーされます。
1178N/Aドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが \-sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスがドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。
1178N/A最初の 2 つのケース (メソッドがオーバーライドしている場合) では、Javadoc ツールは、そのコメントが継承されているかどうかにかかわらず、オーバーライドしているメソッドのドキュメント内に「オーバーライド」という小見出しを生成し、オーバーライドされているメソッドへのリンクを書き込みます。
1178N/A3 つ目のケース (特定のクラスのメソッドがインタフェースのメソッドを実装している場合) では、javadoc ツールは、オーバーライドしているメソッドのドキュメント内に「定義」という小見出しを生成し、実装されているメソッドへのリンクを書き込みます。これは、コメントが継承されているかどうかにかかわりません。
1178N/A\f3メソッドの説明が継承されるアルゴリズム\fP \- あるメソッドにドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、Javadoc ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。 このアルゴリズムは、もっとも適切なドキュメンテーションコメントを検索できるように設計されており、スーパークラスよりもインタフェースが優先されるようになっています。
1178N/A直接に実装されている (または、拡張されている) インタフェースを、メソッドの宣言で implements (または extends) キーワードのあとに登場する順序で、1 つずつ調べる。このメソッドについて最初に見つかったドキュメンテーションコメントを採用する
1178N/A手順 1 でドキュメンテーションコメントが見つからなかった場合は、直接実装されている (または、拡張されている) インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ)
1178N/AJavadoc ツールは、Java のドキュメンテーションコメント内に埋め込まれた特別なタグを解析します。これらのドキュメンテーションタグを使うと、書式の整った完全な API ドキュメントをソースコードから自動的に生成できます。タグは、単価記号 (\f2@\fP) で始まり、大文字と小文字が区別されます。 これらのタグは、定められたとおりの大文字と小文字を使用して記述する必要があります。タグは、行の先頭 (先行する空白と省略可能なアスタリスクは除く) に置かなければなりません。慣例として、同じ名前のタグは 1 か所にまとめて記述するようにします。たとえば、\f2@see\fP タグが複数ある場合は、すべてを 1 か所にまとめて記述します。
1178N/A\-author オプションが使われている場合、生成ドキュメントに「著者」の項目を追加し、指定された \f2name\-text\fP を書き込みます。1 つのドキュメンテーションコメントに複数の \f2@author\fP タグを含めることができます。1 つの \f2@author\fP タグに 1 つの名前を指定することも、1 つのタグに複数の名前を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (\f2,\fP) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@authorを参照してください。
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/deprecation.htmlを使って特定のプログラム要素を非推奨にできるようになりました。
1178N/Aこの API は動作し続けますが、この API を使用するべきではないことを示すコメントを追加します。Javadoc ツールは、\f2deprecated\-text\fP を主説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
1178N/A\f2deprecated\-text\fP の最初の文では、少なくとも、その API が推奨されなくなった時期と、代替使用するべき API を読者に提示する必要があります。Javadoc ツールは、この最初の文だけを、概要セクションと索引にコピーします。そのあとの文では、その API が推奨されない理由を説明することもできます。また、代わりの API を指し示す \f2{@link}\fP タグ (Javadoc 1.2 以降の場合) を含める必要があります。 次のように記述します。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@deprecatedを参照してください。
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/index.htmlのドキュメントを参照してください。
1178N/Aテキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、\f2text\fP を \f2code\fP フォントで表示します。これにより doc コメントでは、パラメータの種類 (\f2<Object>\fP)、不等号 (\f23 < 4\fP)、または矢印 (\f2<\-\fP) などで、HTML エンティティー (\f2<\fP および \f2>\fP) ではなく、通常の山括弧 (\f2<\fP および \f2>\fP) を使用できます。たとえば doc コメントのテキスト
1178N/A生成されるページから見た、生成ドキュメントの (生成先の) ルートディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの下部から著作権のページにリンクします。
1178N/Aこの \f2{@docRoot}\fP タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
1178N/A javadoc \-bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
1178N/A\- \f2{@docRoot}\fP をこのように利用する場合、一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする必要があります。たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、「\f2{{@docRoot}}\fP」のように、中括弧を二重にする必要があります。さらに、\f2\-bottom\fP などのオプションに対する引数を、単一引用符ではなく、二重引用符で囲む必要があります。 \f2href\fP 引数の値を囲む引用符は省略します。
1178N/A * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
1178N/A <a href="{@docRoot}/copyright.html">
1178N/Aもっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーションコメントに、ドキュメントを継承 (コピー) します。この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。
1178N/A継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。
1178N/A{@link\ \ package.class#member\ \ label}\
1178N/A表示テキスト \f2label\fP とのインラインリンクを挿入します。 \f2label\fP は、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。
1178N/Aこのタグは、\f2@see\fP タグとよく似ています。 どちらのタグも、\f2package.class\fP\f2#\fP\f2member\fP および \f2label\fP の参照の仕方が同じで、有効な構文もまったく同じです。大きな違いは、\f2{@link}\fP は、リンクを [関連項目] セクションに置くのではなく、インラインリンクを生成するということです。また、インラインテキストのほかの部分と区別するために、\f2{@link}\fP タグの最初と最後に中括弧を記述します。ラベルの中で「}」を使う必要がある場合は、HTML エンティティーの「}」を使います。
1178N/A1 つの文の中で使用できる \f2{@link}\fP タグの数に制限はありません。このタグは、ドキュメンテーションコメントの主説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。
1178N/A<a href="Component.html#getComponentAt(int, int)">getComponentAt</a> メソッドを使用します。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#{@link}を参照してください。
1178N/A{@linkplain\ package.class#member\ label}
1178N/Aテキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、\f2text\fP を表示します。これにより doc コメントでは、パラメータの種類 (\f2<Object>\fP)、不等号 (\f23 < 4\fP)、または矢印 (\f2<\-\fP) などで、HTML エンティティー (\f2<\fP および \f2>\fP) ではなく、通常の山括弧 (\f2<\fP および \f2>\fP) を使用できます。たとえば doc コメントのテキスト
1178N/A指定した \f2parameter\-name\fP と指定した \f2description\fP を使用してパラメータを「Parameters」セクションに追加します。doc コメントを記述するときは、\f2description\fP を複数行に続けることができます。このタグは、メソッド、コンストラクタ、またはクラスの doc コメント内でのみ有効です。
1178N/A\f2parameter\-name\fP は、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタのタイプパラメータの名前になります。山括弧でパラメータ名を囲むと、型パラメータを使用することを指定します。
1178N/A[戻り値] セクションを追加して、\f2description\fP のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@returnを参照してください。
1178N/A[関連項目] 見出しを追加し、\f2reference\fP を指すリンクか、またはテキストエントリを書き込みます。1 つのドキュメンテーションコメントには、任意の数の \f2@see\fP タグを指定できます。 すべての \f2@see\fP タグの内容は、同じの見出しの下にグループ化されます。\f2@see\fP タグには、次の 3 種類の形式があります。 もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバーに対するインラインリンクを文中に挿入する方法は、\f2{@link}\fP を参照してください。
1178N/A\f2string\fP のテキストエントリを追加します。リンクは生成されません。\f2string\fP は、書籍または URL ではアクセスできない情報の参照先です。Javadoc ツールは、最初の文字が二重引用符 (\f2"\fP) かどうかを調べて、この形式をほかの 2 つの形式と区別します。例を示します。
1178N/A\f2URL\fP#\f2value\fP で定義されたとおりにリンクを追加します。\f2URL\fP#\f2value\fP は、相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (\f2<\fP) かどうかを調べて、この形式をほかの 2 つの形式と区別します。例を示します。
1178N/A@see\ package.class#member\ label
1178N/A指定された名前を持つ、参照されている Java 言語のメンバーについてのドキュメントを指すリンクを、表示テキスト \f2label\fP とともに追加します。\f2label\fP は省略可能です。 \f2label\fP を省略すると、リンク先のメンバーの名前が適切に短縮されて表示されます。 「名前が表示される方法」を参照してください。\-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。
1178N/Aバージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。 1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。
1178N/A\f4package.class\fP\f4#\fP\f4member\fP には、参照されている任意の有効なプログラム要素の名前を指定します。 つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。 ただし、メンバー名ーの前のドットは、シャープ記号 (\f2#\fP) で置き換えます。\f2class\fP は、任意のトップレベルまたは入れ子にされたクラスまたはインタフェースを表します。\f2member\fP は、任意のコンストラクタ、メソッドまたはフィールド (入れ子にされたクラスまたはインタフェースではない) を表します。指定した名前が、ドキュメント化されているクラスに含まれている場合、Javadoc ツールは、その名前へのリンクを自動的に作成します。外部参照クラスへのリンクを作成するには、\f2\-link\fP オプションを使います。参照クラスに属していない名前のドキュメントを参照するには、ほかの 2 つの形式の \f2@see\fP タグを使います。この引数については、このあとの「名前の指定」で詳しく説明します。
1178N/A\f4label\fP は、省略可能なテキストで、リンクのラベルとして表示されます。\f2label\fP には空白を含めることができます。\f2label\fP を省略すると、\f2package.class.member\fP が、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。 「名前が表示される方法」を参照してください。
1178N/A空白文字は、\f2package.class\fP\f2#\fP\f2member\fP と \f2label\fP の間の区切り文字です。括弧の内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。
1178N/A\f3例\fP \- この例では、\f2Character\fP クラスにある \f2@see\fP タグが、\f2String\fP クラスの \f2equals\fP メソッドを参照しています。タグには、名前 \f2String#equals(Object)\fP とラベル \f2equals\fP の両方の引数が含まれています。
1178N/A\f3名前の指定\fP \- このタグに指定する \f2package.class\fP\f2#\fP\f2member\fP という名前は、\f2java.lang.String#toUpperCase()\fP のように完全指定することも、\f2String#toUpperCase()\fP や \f2#toUpperCase()\fP のように部分的に指定することもできます。名前が完全指定されていない場合、Javadoc ツールは、Java コンパイラの通常の検索順序でその名前を検索します。詳細は、このあとの「@see の検索順序」を参照してください。名前には、メソッドの複数の引数の間など、括弧の内側であれば空白を含めることができます。
1178N/A「部分的に指定」した短い名前を指定することの利点は、入力する文字数が減ることや、ソースコードが読みやすくなることです。次の表に、さまざまな形式の名前を示します。 この表の中で、\f2Class\fP にはクラスまたはインタフェースを、\f2Type\fP にはクラス、インタフェース、配列、または基本データ型を、そして \f2method\fP にはメソッドまたはコンストラクタを指定できます。
1178N/A\f4@see\fP\f3\ \fP\f4package.class#member\fP\f3 の一般的な形式\fP
1178N/A\f2@see\fP\ \f2Class.NestedClass\fP
1178N/A\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2field\fP
1178N/A\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2method(Type,\ Type,...)\fP
1178N/A\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP
1178N/A\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2constructor(Type,\ Type,...)\fP
1178N/A\f2@see\fP\ \f2package.Class\fP\f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP
1178N/A\f2@see\fP\ \f2package.Class.NestedClass\fP
1178N/A\f2@see\fP\ \f2package.Class\fP
1178N/A最初の種類の形式 (パッケージとクラスを省略) の場合、Javadoc ツールは、現在のクラスの階層だけを検索します。つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、または現在のクラスかインタフェースを囲んでいるクラスかインタフェースからメンバーを検索します (このあとの検索手順 1 〜 3)。現在のパッケージのほかの部分や、ほかのパッケージは検索しません (検索手順 4 〜 5)。
1178N/Aメソッドまたはコンストラクタを指定するときに括弧を付けずに名前だけ (\f2getValue\fP など) を使用した場合、同じ名前のフィールドが存在しなければ、Javadoc ツールはそのメソッドに対して正しくリンクを作成します。 ただし、括弧と引数を追加するように促す警告メッセージを出力します。このメソッドがオーバーロードされている場合、Javadoc ツールは、検索で最初に見つかったメソッドにリンクします。 結果は前もって特定できません。
1178N/Aすでに述べたとおり、クラスとメンバーを区切るために、ドット (\f2.\fP) ではなくシャープ記号 (\f2#\fP) を使用することに注意してください。このように指定すると、Javadoc ツールは、あいまいさを解決できます。 ドットは、クラス、入れ子にされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されます。ただし、Javadoc ツールでは一般に許容範囲が広く、あいまいさがなければ、ドットでも正しく解析されます。 その場合でも警告は表示されます。
1178N/A\f3@see の検索順序\fP \- Javadoc ツールは、ソースファイル (.java)、パッケージファイル (package.html または package\-info.java)、または概要ファイル (overview.html) の中に登場する \f2@see\fP タグを処理します。後者の 2 つのファイルでは、完全指定の名前を \f2@see\fP タグに指定しなければなりません。ソースファイルでは、完全指定の名前、または部分指定の名前を指定できます。
1178N/AJavadoc ツールは、\f2.java\fP ファイル内で完全指定でない名前が記述された \f2@see\fP タグを見つけると、Java コンパイラと同じ順序で指定された名前を検索します。 ただし、Javadoc ツールは、特定の名前空間のあいまいさを検出しません。 これは、ソースコードにこれらのエラーが存在していないことを前提としているためです。この検索順序は、Java 言語仕様第 2 版の第 6 章「Names」で正式に定義されています。Javadoc ツールは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてから名前を検索します。具体的には、次の順序で検索します。
1178N/AJavadoc ツールは、各クラスについて手順 1 〜 3 を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にそのクラスを囲んでいるクラス E を検索し、その次に E のスーパークラスを検索し、さらにその次に E を囲んでいるクラスを検索します。 手順 4 と 5 では、1 つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません。 その順序は、個々のコンパイラによって異なります。手順 5 では、Javadoc ツールは、java.lang を検索します。 このパッケージは、すべてのプログラムに自動的にインポートされるからです。
1178N/AJavadoc ツールは、必ずしもサブクラスを検索するとは限りません。 また、javadoc の実行中にほかのパッケージのドキュメントが生成される場合でも、ほかのパッケージを検索しません。たとえば、\f2@see\fP タグが \f2java.awt.event.KeyEvent\fP クラス内にあって、\f2java.awt\fP パッケージにある名前を参照している場合、Javadoc は、そのクラスがインポートしないかぎりそのパッケージを検索しません。
1178N/A\f3名前が表示される方法\fP \- \f2label\fP を省略すると、\f2package.class.member\fP が表示されます。一般に、package.class.member は、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけが表示されるということです。たとえば、\f2String.toUpperCase()\fP メソッドに、同じクラスのメンバーへの参照とほかのクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。
1178N/A\f4String.toUpperCase()\fP\f3 での例\fP
1178N/A\f2Character.toLowerCase(char)\fP (パッケージ名は省略し、クラス名を含む)
1178N/A\f2@see java.io.File#exists()\fP
1178N/A\f2java.io.File.exists()\fP (パッケージ名とクラス名を含む)
1178N/A右側のコメントは、\f2@see\fP タグが別のパッケージ (\f2java.applet.Applet\fP など) のクラス内にある場合に、名前がどのように表示されるかを示しています。
0N/A@see java.lang.String // String \fP\f3
0N/A@see java.lang.String The String class // The String class \fP\f3
0N/A@see String#equals(Object) // String.equals(Object) \fP\f3
0N/A@see Character#MAX_RADIX // Character.MAX_RADIX \fP\f3
1178N/A\f2field\-description\fP (省略可能) では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要に応じて、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式のページに追加します。
1178N/A\f2include\fP および \f2exclude\fP 引数は、直列化された形式のページにクラスまたはパッケージを含めるか除外するかを示します。これらの引数には、次のような効果があります。
1178N/A\f2Serializable\fP を実装している public または protected クラスは、通常はそのページに含められます。 ただし、そのクラスまたはそのクラスが属するパッケージが \f2@serial exclude\fP で指定されていると、そのページから除外されます。
1178N/A\f2Serializable\fP を実装している private または package private クラスは、通常はそのページから除外されます。 ただし、そのクラスまたはそのクラスが属するパッケージが \f2@serial include\fP で指定されていると、そのページに含められます。
1178N/A例: \f2javax.swing\fP パッケージは、\f2@serial exclude\fP で指定されています (\f2package.html\fP または \f2package\-info.java\fP 内)。public クラス \f2java.security.BasicPermission\fP は、\f2@serial exclude\fP で指定されています。package private クラス \f2java.util.PropertyPermissionCollection\fP は、\f2@serial include\fP で指定されています。
1178N/Ahttp://java.sun.com/products/jdk/serialization/faq/#javadoc_warn_missingも参照してください。 この FAQ には、「\-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、
1178N/A\f2Serializable\fP クラスの \f2serialPersistentFields\fP メンバーの \f2ObjectStreamField\fP コンポーネントをドキュメント化します。各 \f2ObjectStreamField\fP コンポーネントに対して \f2@serialField\fP タグを 1 つ使う必要があります。
1178N/A\f2data\-description\fP は、直列化された形式でのデータの型と順序を説明するテキストです。このデータには、特に、\f2writeObject\fP メソッドによって書き込まれる省略可能なデータ、および \f2Externalizable.writeExternal\fP メソッドによって書き込まれるすべてのデータ (基底クラスを含む) が含まれます。
1178N/A\f2@serialData\fP タグは、\f2writeObject\fP、\f2readObject\fP、\f2writeExternal\fP、\f2readExternal\fP、\f2writeReplace\fP、および \f2readResolve\fP メソッドのドキュメンテーションコメントで使用できます。
1178N/A生成ドキュメントに [導入されたバージョン] 見出しを追加し、指定された \f2since\-text\fP を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、\f2since\-text\fP に示されたソフトウェアリリース以降、存在していることを意味します。例を示します。
1178N/AJava プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。 その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。
1178N/A\f2@throws\fP タグと \f2@exception\fP タグは同義です。生成ドキュメントに [例外] 小見出しを追加して、\f2class\-name\fP と \f2description\fP テキストを書き込みます。\f2class\-name\fP は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタの doc コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、Javadoc ツールは、検索順序に従ってクラスを探します。同じまたは異なる例外の doc コメントで、複数の \f2@throws\fP タグを使用できます。
1178N/Aすべてのチェック済み例外がドキュメント化されるようにするために、\f2@throws\fP タグが throws 節内の例外用に存在しない場合は、@throws タグのあるドキュメントであるかのように、Javadoc ツールによって例外が HTML 出力に説明なしで自動的に追加されます。
1178N/Aオーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、\f2@throws\fP ドキュメンテーションをそのメソッドからサブクラスにコピーされます。インタフェースメソッドから実装メソッドにコピーされる場合も同様です。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@exceptionを参照してください。
1178N/A{@value\ package.class#field}
1178N/A任意の doc コメント内で引数 \f2package.class#field\fP ありで使用されている場合は、指定した定数の値が表示されます。
1178N/A引数 \f2package.class#field\fP は、@see 引数と同一の形式になります。ただし、メンバーが静的フィールドになければならない点が異なります。
1178N/A\-version オプションが使われている場合、生成ドキュメントに [バージョン] 小見出しを追加して、指定された \f2version\-text\fP を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。 これに対し、@since は、このコードが導入されたバージョン番号を保持します。\f2version\-text\fP には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。
1178N/A1 つのドキュメンテーションコメントに複数の \f2@version\fP タグを含めることができます。必要に応じて、\f2@version\fP タグごとに 1 つのバージョン番号を指定することも、タグごとに複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (\f2,\fP) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@versionを参照してください。
1178N/Aここでは、タグを使用できる場所について説明します。\f2@see\fP、\f2@since\fP、\f2@deprecated\fP、\f2{@link}\fP、\f2{@linkplain}\fP および \f2{@docroot}\fP のタグは、すべての doc コメントで使用できます。
1178N/A概要タグは、概要ページのドキュメンテーションコメントで使用できるタグです。 このドキュメンテーションコメントは、通常 \f2overview.html\fP という名前ソースファイル内にあります。ほかのドキュメンテーションコメントの場合と同様に、これらのタグは、主説明のあとで使う必要があります。
1178N/A\f3注\fP \- バージョン 1.2 では、概要ドキュメント内の \f2{@link}\fP タグにバグがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、\f2{@docRoot}\fP タグは、概要ドキュメント内では動作しません。
1178N/Aパッケージタグは、パッケージのドキュメンテーションコメントで使用できるタグです。 このドキュメンテーションコメントは、\f2package.html\fP または \f2package\-info.java\fP という名前のソースファイル内にあります。ここで使用できる \f2@serial\fP タグは、\f2include\fP または \f2exclude\fP 引数を指定したものだけです。
1178N/A次に、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグを示します。ここで使用できる \f2@serial\fP タグは、\f2include\fP または \f2exclude\fP 引数を指定したものだけです。
1178N/A * @see java.awt.BaseWindow
1178N/A * @see java.awt.Button
1178N/A次に、コンストラクタまたはメソッドのドキュメンテーションコメント内で表示できるタグを示します。 ただし、\f2@return\fP はコンストラクタでは表示できず、\f2{@inheritDoc}\fP は表示に制限があります。\f2@serialData\fP タグは特定の直列化メソッドの doc コメントでのみ使用できます。
1178N/A * @see java.lang.Character#charValue()
1178N/Ajavadoc ツールは、ドックレットを使って出力を決定します。Javadoc ツールは、\-doclet オプションでカスタムドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使います。Javadoc ツールには、任意のドックレットとともに使用できるコマンド行オプションがあります。 これらのオプションについては、このあとの「Javadoc オプション」で説明します。標準ドックレットでは、このほかに、いくつかの追加のコマンド行オプションが提供されます。 これらのオプションについては、そのあとの「標準ドックレットが提供するオプション」で説明します。どのオプション名も、大文字と小文字が区別されません。 ただし、オプションの引数では、大文字と小文字が区別されます。
1178N/A\f2イタリック\fPで示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。
1178N/A\-overview \ path/filename
1178N/AJavadoc に対して、\f2path/filename\fP で指定された「ソース」ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ (\f2overview\-summary.html\fP) に配置するように指定します。\f2path/filename\fP は、\f2\-sourcepath\fP への相対パスです。
1178N/A\f2filename\fP と \f2path\fP には、それぞれ任意の名前と場所を指定できますが、通常は、\f2overview.html\fP という名前を付けて、ソースツリー内の最上位のパッケージディレクトリがあるディレクトリに配置します。この場所に配置すると、\f2\-sourcepath\fP によってこのファイルが指し示されるので、パッケージをドキュメント化する際に \f2path\fP が不要になります。たとえば、\f2java.lang\fP パッケージのソースツリーが \f2/src/classes/java/lang/\fP の場合、概要ファイルを \f2/src/classes/overview.html\fP に配置できます。「使用例」を参照してください。
1178N/A\f2path/filename\fP で指定するファイルについては、「概要コメントファイル」を参照してください。
1178N/Aドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。完全指定の名前を指定してください。このドックレットにより、出力の内容と形式が定義されます。\f4\-doclet\fP オプションが使われていない場合、Javadoc は、標準ドックレットを使ってデフォルトの HTML 形式を生成します。このクラスには、\f2start(Root)\fP メソッドが含まれていなければなりません。この起動クラスへのパスは、\f2\-docletpath\fP オプションによって定義されます。
1178N/A\f2\-doclet\fP オプションで指定されているドックレット開始クラスファイル、およびそれが依存するすべての jar ファイルへのパスを指定します。開始クラスファイルが jar ファイル内にある場合、以下の例のように jar ファイルのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。\f2classpathlist\fP には、複数のパスまたは JAR ファイルを含めることができます。 その場合、各パスまたは JAR ファイルを、Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。
0N/A \-docletpath /home/user/mifdoclet/lib/mifdoclet.jar
0N/A \-docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/
1178N/A\f2この機能は、Javadoc 1.4 では削除されました。代替機能はありません。このオプションは、Javadoc 1.1 によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした。 入れ子のクラスはサポートされていません。このオプションが必要な場合は、Javadoc 1.2 または 1.3 を使用してください。\fP
1178N/AJavadoc は、JDK 1.5 で導入された総称および他の言語機能を含んだコードを受け付けます。\f3\-source\fP フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。
1178N/A\f2javadoc\fP コマンドにパッケージ名または \f2\-subpackages\fP を渡すときに、ソースファイル (\f2.java\fP) を検索するためのパスを指定します。\f2sourcepathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソースファイルの位置だけでなく、それ自体はドキュメント化されないがドキュメント化されるソースファイルから継承されたコメントを持つソースファイルの位置も確認できます。
1178N/A\f2\-sourcepath\fP オプションは、javadoc コマンドにパッケージ名を渡すときにだけ使用できます。 \f2javadoc\fP コマンドに渡される \f2.java\fP ファイルは、このパスからは検索されません。\f2.java\fP ファイルを検索するには、そのファイルのあるディレクトリに cd によって移動するか、または各ファイルの先頭にパスを含めます (「1 つ以上のクラスのドキュメント化」を参照)。\f2\-sourcepath\fP が省略された場合、Javadoc は、クラスパスを使ってソースファイルを検索します (\-classpath を参照)。したがって、デフォルトの \-sourcepath は、クラスパスの値です。\-classpath も省略してパッケージ名を Javadoc に渡すと、Javadoc は現在のディレクトリおよびそのサブディレクトリからソースファイルを検索します。
1178N/A\f2sourcepathlist\fP には、ドキュメント化するパッケージ名のソースツリーのルートディレクトリを設定します。たとえば、\f2com.mypackage\fP というパッケージをドキュメント化する場合に、そのソースファイルが次の場所にあるとします。
1178N/Aこの場合、次のようにして \f2sourcepath\fP を \f2/home/user/src\fP、つまり \f2com/mypackage\fP を含むディレクトリに指定し、それからパッケージ名 \f2com.mypackage\fP を指定します。
1178N/Aこの方法は、ソースパスの値とパッケージ名を連結して、ドットを (円記号) 「\\」に変えると、パッケージのフルパス (C:\\user\\src\\com\\mypackage) になることを理解すると簡単です。\f2/home/user/src/com/mypackage\fP.
1178N/AJavadoc が参照クラス (\f2.class\fP ファイル) を検索するパスを指定します。 参照クラスとは、ドキュメント化されるクラスとそれらのクラスによって参照されるすべてのクラスのことです。\f2classpathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパスの以下すべてのサブディレクトリを検索します。\f2classpathlist\fP を指定するときは、
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/tools/index.html#generalのドキュメントにある指示に従ってください。
1178N/A\f2\-sourcepath\fP が省略されている場合、Javadoc ツールは、\f2\-classpath\fP を使って、クラスファイルだけでなくソースファイルも検索します (下位互換性のため)。したがって、ソースファイルとクラスファイルを別々のパスから検索する必要がある場合は、\f2\-sourcepath\fP と \f2\-classpath\fP の両方を使います。
1178N/Aたとえば、\f2com.mypackage\fP をドキュメント化する場合に、ソースファイルがディレクトリ \f2/home/user/src/com/mypackage\fP にあり、このパッケージが \f2/home/user/lib\fP 内のライブラリを使うのであれば、次のように指定します。
1178N/Aほかのツールと同様に、\f2\-classpath\fP が指定されていない場合は、CLASSPATH 環境変数が設定されていれば、Javadoc ツールはこの環境変数を使います。どちらも設定されていない場合、Javadoc ツールは現在のディレクトリからクラスを検索します。
1178N/AJavadoc ツールは拡張機能クラスおよびブートストラップクラスに関連しているため、Javadoc ツールが \f2\-classpath\fP を使用してユーザークラスを検索する方法についての詳細は、
1178N/A便宜上、\f2*\fP のベース名を含むクラスパス要素は、ディレクトリ内の拡張子 \f2.jar\fP または \f2.JAR\fP を持つすべてのファイルのリストを指定するのと同じとみなされます (Java プログラムはこの 2 つの呼び出しを区別できない)。
1178N/Aたとえば、ディレクトリ \f2foo\fP に \f2a.jar\fP と \f2b.JAR\fP が含まれている場合、クラスパス要素 \f2foo/*\fP は \f2A.jar:b.JAR\fP に展開されます。 ただし、JAR ファイルの順番は指定されません。このリストには、隠しファイルも含め、指定されたディレクトリ内のすべての JAR ファイルが含まれます。\f2*\fP だけから成るクラスパスエントリは、カレントディレクトリ内のすべての JAR ファイルのリストに展開されます。\f2CLASSPATH\fP 環境変数も、定義時には同様に展開されます。クラスパスのワイルドカード展開は必ず、Java 仮想マシンの起動前に実行されます。したがって、\f2System.getenv("CLASSPATH")\fP 呼び出しのように環境に問い合わせを行わない限り、Java プログラムが展開されていないワイルドカードを認識することはありません。
1178N/Aソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 \f2package\fP 引数は、任意の最上位サブパッケージ (\f2java\fP など) または完全指定のパッケージ (\f2javax.swing\fP など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、\f2\-sourcepath\fP を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。
1178N/Aこのコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。
1178N/A指定されたパッケージとそのサブパッケージを \f2\-subpackages\fP によって作成されたリストから無条件に除外します。過去の \f2\-subpackages\fP オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。例を示します。
1178N/Aこのうち、\f2java.io\fP、\f2java.util\fP、\f2java.math\fP は組み込まれますが、\f2java.net\fP と \f2java.lang\fP 以下のパッケージは除外されます。ただし、\f2java.lang\fP のサブパッケージである \f2java.lang.ref\fP は除外されます。
1178N/Aブートクラスが存在するパスを指定します。ブートクラスとは、通常、Java プラットフォームのコアクラスのことです。ブートクラスパスは、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfilesを参照してください。\f2classpathlist\fP 内の複数のディレクトリは、コロン (:) で区切ります。
1178N/A拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java 拡張機能機構を使うすべてのクラスです。extdirs は、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、前述の \f2\-classpath\fP を参照してください。\f2dirlist\fP 内の複数のディレクトリは、コロン (:) で区切ります。
1178N/Ajavadoc の実行中に詳細なメッセージを表示します。verbose オプションを指定しないと、ソースファイルのロード時、ドキュメントの生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時にメッセージが表示されます。verbose オプションを指定すると、各 Java ソースファイルの解析に要した時間 (ミリ秒単位) など、追加のメッセージが表示されます。
1178N/Ahttp://java.sun.com/javase/6/docs/api/java/text/BreakIterator.html の国際化された文境界を使用して、英文の最初の文の終わりを判断します (他のすべてのロケールはすでに \f2BreakIterator\fP を使用)。\f2「最初の文」\fPとは、パッケージ、クラス、またはメンバーの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバーの要約にコピーされ、アルファベット順のインデックスにコピーされます。
1178N/AJDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2 以降では、\f2\-breakiterator\fP オプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。
1178N/Abreakiterator 文区切りアルゴリズム \- 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは、ほとんどの省略表記が処理される (「The serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する
1178N/A注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\\\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。 この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。この件で皆様に余分の手間をおかけし、混乱を招いたことをお詫びいたします。
1178N/A\f3重要\fP \- \f2\-locale\fP オプションは、標準ドックレットが提供するすべてのオプション、またはその他の任意のドックレットの提供するすべてのオプションより前 (左側) に指定する必要があります。そうしないと、ナビゲーションバーが英語で表示されます。このコマンド行オプションだけは、指定する順序に依存します。
1178N/AJavadoc がドキュメントを生成するときに使うロケールを指定します。引数には、java.util.Locale のドキュメントで説明されているロケールの名前を指定します。たとえば、\f2en_US\fP (英語、米国)、\f2en_US_WIN\fP (Windows で使われる英語) などを指定します。
1178N/Aロケールを指定すると、指定したロケールのリソースファイルが Javadoc によって選択されて、メッセージ (ナビゲーションバー、リストと表の見出し、ヘルプファイルの目次、stylesheet.css のコメントなどの文字列) のために使われます。また、アルファベット順にソートされるリストのソート順、および最初の文の末尾を判別するための文の区切り文字も、指定したロケールによって決まります。ただし、このオプションは、ドキュメント化されるクラスのソースファイル内で指定されているドキュメンテーションコメントのテキストのロケールを決定するものではありません。
1178N/Aソースファイルのエンコーディングの名前 (\f2EUCJIS/SJIS\fP など) を指定します。このオプションが指定されていない場合は、プラットフォームのデフォルトコンバータが使われます。
1178N/Ajavadoc を実行する実行時システム java に、\f2flag\fP を直接渡します。\f2J\fP と \f2flag\fP の間に空白を入れてはなりません。たとえば、生成ドキュメントを処理するためにシステムで 32M バイトのメモリーを確保しておく必要がある場合は、Java の \f2\-Xmx\fP オプションを次のように呼び出します。 \f2\-Xms\fP は、省略可能です。 これは、初期メモリーのサイズを設定するだけのオプションで、必要なメモリーの最小サイズがわかっている場合に便利です。
1178N/A % \fP\f3javadoc \-J\-Xmx32m \-J\-Xms32m\fP \f3com.mypackage\fP
1178N/A生成された HTML ファイルを保存する生成先ディレクトリを指定します(「d」は「生成先 (destination)」の意味)。このオプションを省略すると、生成されたファイルは現在のディレクトリに保存されます。値 \f2directory\fP には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。バージョン 1.4 では、javadoc を実行すると生成先ディレクトリが自動的に作成されます。
1178N/Aドキュメント化されるクラスおよびパッケージごとに 1 つの [使用] ページを組み込みます。このページには、その特定のクラスまたはパッケージの API を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラス C を例にとると、クラス C を使っているものとしては、C のサブクラス、C として宣言されているフィールド、C を返すメソッド、および、型 C のパラメータを持つメソッドとコンストラクタがあります。
1178N/Aたとえば、String の [使用] ページに何が表示されるかを見てみましょう。\f2java.awt.Font\fP クラスの \f2getName()\fP メソッドは、\f2String\fP 型を返します。したがって、\f2getName()\fP は \f2String\fP を使っているので、\f2String\fP の [使用] ページにはこのメソッドがあります。
1178N/Aただし、ドキュメント化されるのは API の使用だけであって、実装はドキュメント化されません。あるメソッドが、その実装の中で \f2String\fP を使っていても、引数として文字列をとったり、文字列を返したりしない場合は、\f2String\fP の「使用」とはみなされません。
1178N/A生成ドキュメントに、@version のテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用している Javadoc ツールのバージョンを確認するには、\f2\-J\-version\fP オプションを使用します。
1178N/AHTML の <title> タグに配置するタイトルを指定します。指定したタイトルは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク (お気に入り) に表示されます。このタイトルには HTML タグを含めないでください。 タイトルに HTML タグが含まれていると、ブラウザがタグを正しく解釈できません。\f2title\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。\-windowtitle が省略されている場合、Javadoc ツールは、このオプションの代わりに \-doctitle の値を使います。
1178N/A % \fP\f3javadoc \-windowtitle "Java 2 Platform" com.mypackage\fP
1178N/A概要ファイルの最上部の近くに配置するタイトルを指定します。タイトルは中央揃えになり、レベル 1 の見出しとして、上部ナビゲーションバーのすぐ下に置かれます。\f2title\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2title\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
1178N/A % \fP\f3javadoc \-doctitle "Java (TM)" com.mypackage\fP
1178N/A\f3このオプションは、現在は存在しません。\fPJavadoc 1.2 のベータ版にだけ存在しました。このオプションは、\f2\-doctitle\fP という名前に変更されました。名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。
1178N/A各出力ファイルの上端に配置するヘッダーテキストを指定します。ヘッダーは、上部ナビゲーションバーの右側に配置されます。\f2header\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2header\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
0N/A % \fP\f3javadoc \-header "<b>Java 2 Platform </b><br>v1.4" com.mypackage\fP
1178N/A各出力ファイルの下端に配置するフッターテキストを指定します。フッターは、下部ナビゲーションバーの右側に配置されます。 \f2footer\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2footer\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
1178N/A各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーションバーより下の、ページの最下部に配置されます。\f2text\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2text\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。
1178N/A\f4extdocURL\fP は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。あとで例を示します。このディレクトリ内にパッケージリストファイルが存在していなければなりません。 存在しない場合は、\f2\-linkoffline\fP を使用します。Javadoc ツールは、\f2パッケージリスト\fPファイルからパッケージ名を読み取り、これらのパッケージをその URL にリンクします。Javadoc ツールを実行すると、作成される \f2<A HREF>\fP リンク内に \f2extdocURL\fP の値がそのままコピーされます。したがって、\f2extdocURL\fP はファイルへの URL ではなく「ディレクトリへの URL」でなければなりません。
1178N/A\f2extdocURL\fP への絶対リンクを使用すると、ユーザーのドキュメントを任意の Web サイト上のドキュメントにリンクできます。 相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクを使用する場合、\f2\-d\fP を使って、生成先ディレクトリからリンクされるパッケージのあるディレクトリの相対パスを指定する必要があります。
1178N/A通常、絶対リンクを指定する場合は、\f2http:\fPリンクを使用します。Web サーバーを持たないファイルシステムにリンクする場合は、\f2file:\fP リンクを使用できます。ただし、この方法は、すべてのユーザーが生成された同じファイルシステムを共有するドキュメントにアクセスする必要がある場合以外は使用しないでください。
1178N/Aいかなる場合にも、いかなるオペレーティングシステムでも、絶対 URL か相対 URL か、「http:」ベースか「file:」ベースかにかかわらず、スラッシュを区切り文字として使用します (
1178N/Ajavadoc の実行時に複数の \f2\-link\fP オプションを指定して、複数のドキュメントへのリンクを作成することもできます。 \f3\-linkoffline または \-link の選択\fP
1178N/Aプログラムがその URL に接続し、読み取りを行うことがシェルによって許可されていない場合に外部 API ドキュメントへの絶対 URL を使用する場合。このような状況は、リンク先のドキュメントがファイアウォールの向こう側にある場合に発生します。
1178N/Ahttp://java.sun.com/j2se/1.5.0/docs/api 内の \f2java.lang\fP、\f2java.io\fP、その他の Java 2 プラットフォームパッケージにリンクしたい場合があります。 次のコマンドは、\f2com.mypackage\fP パッケージのドキュメントと Java 2 プラットフォームパッケージへのリンクを生成します。生成されたドキュメントには、たとえばクラスツリー内の \f2Object\fP クラスへのリンクが含まれています。\f2\-sourcepath\fP や \f2\-d\fP などの他のオプションは表示されません。
1178N/A\f3外部ドキュメントへの相対リンクの使用例\fP \- 2 つのパッケージがあり、そのドキュメントが Javadoc ツールを複数回実行した結果生成されたものであるとします。 さらに、これらのドキュメントが相対パスで分割されているとします。この例の場合、2 つのパッケージは、API である \f2com.apipackage\fP とSPI (サービスプロバイダインタフェース) である \f2com.spipackage\fP です。ドキュメントの格納先は \f2docs/api/com/apipackage\fP パッケージと \f2docs/spi/com/spipackage\fP パッケージです。API パッケージのドキュメントがすでに生成されていて、現在のディレクトリが \f2docs\fP である場合、次のコマンドを実行することによって、この API ドキュメントへのリンクを持つ SPI パッケージをドキュメント化します。
1178N/A % \fP\f3javadoc \-d ./spi \-link ../api com.spipackage\fP
1178N/A\f2\-link\fP 引数は、生成先ディレクトリ (\f2docs/spi\fP) の相対パスです。
1178N/A\f3詳細\fP \- \f2\-link\fP オプションを使うと、「コードからは参照されていても、Javadoc の今回の実行ではドキュメント化されない」というクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらの HTML ページがある場所を調べ、その場所を \f2extdocURL\fP に指定する必要があります。このオプションを使うと、たとえば、サードパーティーのドキュメントから、\f2http://java.sun.com\fP にある \f2java.*\fP のドキュメントにリンクすることができます。
1178N/A今回の実行で Javadoc によって生成されるドキュメント内の API だけを対象にリンクを作成する場合は、\f2\-link\fP オプションを省略します。\f2\-link\fP オプションが指定されていない場合、Javadoc ツールは、外部参照されたドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所を判別できないからです。
1178N/Aまた、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対して javadoc を実行したあと、別の一式のパッケージに対して javadoc を実行し、これら 2 つのパッケージ群の間にクロスリンクを作成できます。
1178N/A\f3クラスの参照方法\fP \- 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。\f2import\fP 文または宣言で参照する必要があります。次に、クラス \f2java.io.File\fP を参照する方法の例を示します。
1178N/Aすべての種類の \f2import\fP 文の場合: ワイルドカードによるインポート、名前による明示的なインポート、または \f2java.lang.*\fP に対する自動的なインポート。たとえば、次のようにすれば十分です。
1178N/Aこの参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、\f2implements\fP、\f2extends\fP、または \f2throws\fP 文に置きます。
1178N/Aこの結果、\f2\-link\fP オプションを使用しても、この制限のために誤って表示されない多くのリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安全な方法は上で説明したとおり、当該のクラスをインポートすることです。
1178N/A\f3パッケージリスト\fP \- \f2\-link\fP オプションは、\f2package\-list\fP という名前のファイルを要求します。 このファイルは、Javadoc ツールによって生成され、\f2\-link\fP によって指定した URL に存在します。\f2package\-list\fP ファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキストファイルです。前の例では、Javadoc ツールは指定された URL にある \f2package\-list\fP という名前のファイルを探し、パッケージ名を読み込んで、その URL にあるそれらのパッケージへのリンクを作成しました。
1178N/Ahttp://java.sun.com/j2se/1.5.0/docs/api/package\-list にあり、次のような内容で始まっています。
1178N/A\f2\-link\fP オプションを指定せずに javadoc を実行した場合、外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、\f2\-link\fP オプションを指定した場合は、指定した \f2extdocURL\fP にある \f2package\-list\fP ファイルから該当するパッケージ名が検索されます。パッケージ名が見つかると、\f2extdocURL\fP が名前の前に付加されます。
1178N/Aすべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定した URL に存在していなければなりません。Javadoc ツールは、指定された package\-list が存在するかどうかを調べるだけで、指定された URL に目的のページが存在するかどうかはチェックしません。
1178N/A\f3複数のリンク\fP \- 複数の \f2\-link\fP オプションを指定すると、生成された任意の数の外部ドキュメントに対してリンクを設定できます。Javadoc 1.2 には、複数の \f2\-link\fP オプションを指定できないというバグがあります。これは 1.2.2 で修正されました。
1178N/A\ \ \f2% \fP\f4javadoc \-link\fP \f2extdocURL1\fP \f4\-link\fP \f2extdocURL2\fP \f2...\fP\f4\-link\fP \f2extdocURLn\fP \f4com.mypackage\fP
1178N/A\f2extdocURL1\fP、\f2extdocURL2\fP、... \f2extdocURLn\fP は、それぞれ外部ドキュメントのルートを指し、各ルートには \f2package\-list\fP という名前のファイルが入っています。
1178N/A\f3クロスリンク\fP \- まだ生成されていない 2 つ以上のドキュメントをクロスリンクする場合は、「ブートストラップ」が必要になります。つまり、どのドキュメントについても \f2package\-list\fP が存在していない場合は、最初のドキュメントに対して javadoc ツールを実行する時点で、2 番目のドキュメントの \f2package\-list\fP がまだ存在していません。したがって、外部リンクを作成するには、2 番目のドキュメントを生成したあとで、最初のドキュメントを生成し直す必要があります。
1178N/Aこの場合、最初のドキュメント生成の目的は、そのドキュメントの \f2package\-list\fP を作成することです。 パッケージ名をすべて把握している場合は、package\-list を手動で作成することもできます。次に、2 番目のドキュメントとその外部リンクを生成します。必要な外部の \f2package\-list\fP ファイルが存在しない場合、Javadoc ツールは警告を表示します。
1178N/Aこのオプションは、\f2\-link\fP オプションを変えたものです。 どちらも、javadoc によって生成された外部参照クラスのドキュメントへのリンクを作成します。Javadoc ツール自体がオフラインになっているとき (Web 接続を使ってドキュメントにアクセスできないとき)、Web 上のドキュメントにリンクするには、\f2\-linkoffline\fP オプションを使用します。
1178N/A厳密には、外部ドキュメントの \f2package\-list\fP ファイルにアクセスできないとき、またはこのファイルが \f2extdocURL\fP で指定された場所とは異なる場所 (通常、\f2packageListLoc\fP で指定可能なローカルな場所) に存在するとき、\f2\-linkoffline\fP を使用します。したがって、\f2extdocURL\fP に WWW 上でしかアクセスできない場合は、\f2\-linkoffline\fP を指定することにより、ドキュメントの生成時に javadoc ツールが Web に接続できなければならないという制約がなくなります。
1178N/Aさらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。 こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。
1178N/A\f2\-linkoffline\fP オプションは引数を 2 つ取ります。 最初の引数は \f2<a href>\fP リンクに組み込まれる文字列を指定する引数、2 番目の引数は \f2package\-list\fP の検索場所を指定する引数です。
1178N/A\f4extdocURL\fP は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。相対リンクを使用する場合、\f2\-d\fP を使って、生成先ディレクトリからリンクされるパッケージのルートの相対パスを指定する必要があります。詳細は、\f2\-link\fP オプションの \f2extdocURL\fP を参照してください。
1178N/A\f4packagelistLoc\fP には、外部ドキュメントの \f2package\-list\fP ファイルが入っているディレクトリのパスまたは URL を指定します。これは、URL (http: または file:)or file:)とファイルパスのどちらでもかまいません。また、絶対パスと相対パスのどちらでも指定できます。相対パスの場合は、javadoc が実行されるカレントディレクトリからの相対パスとして指定します。\f2package\-list\fP というファイル名は含めないでください。
1178N/A\f3外部ドキュメントへの絶対リンクを使った例\fP \- \f2http://java.sun.com/j2se/1.5.0/docs/api\fP 内の \f2java.lang\fP、\f2java.io\fP、、およびその他の Java 2 プラットフォームパッケージにリンクしたくても、Web にアクセスできない 場合について考えてみます。この場合は、ブラウザで
1178N/Ahttp://java.sun.com/j2se/1.5.0/docs/api/package\-list にある \f2package\-list\fP ファイルを開き、ローカルディレクトリに保存します。 さらに、2 番目の引数 \f2packagelistLoc\fP にこのローカルコピーの場所を指定します。この例では、パッケージリストファイルはカレントディレクトリ "\f2.\fP" に保存されています。次のコマンドは、Java 2 プラットフォーム API へのリンクを含む、\f2com.mypackage\fP パッケージのドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内の \f2Object\fP クラスへのリンクが含まれています。\f2\-sourcepath\fP などの他の必要なオプションは表示されません。
1178N/A\f3外部ドキュメントへの相対リンクの使用例\fP \- 通常、\f2\-linkoffline\fP に相対パスを指定することはありません。 \f2\-link\fP で同じことができるからです。\f2\-linkoffline\fP を使用する際、\f2package\-list\fP には通常ローカルのファイルを指定します。 相対リンクを使用する際も、リンク先のファイルには通常ローカルのファイルを指定します。したがって、\f2\-linkoffline\fP の 2 つの引数に別々のパスを指定する必要はありません。2 つの引数が同一である場合は、\f2\-link\fP を使用できます。\f2\-link\fP の相対リンクの例を参照してください。
1178N/A\f4package\-list\fP\f3 ファイルを手動で作成\fP \- \f2package\-list\fP ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルを自分で作成し、\f2packagelistLoc\fP でそのパスを指定することができます。\f2com.apipackage\fP が最初に生成され、\f2com.spipackage\fP のパッケージリストが存在しないという前出の例を参照してください。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、\f2package\-list\fP ファイルが生成されない Javadoc 1.0 や 1.1 などで生成されたパッケージ向けに \f2package\-list\fP ファイルを作成するときにも、この方法を利用します。同様に、2 つの会社が未公開の \f2package\-list\fP ファイルを共有することもできるため、クロスリンクを設定したドキュメントを同時にリリースすることも可能です。
1178N/A\f3複数のドキュメントへのリンク\fP \- \f2\-linkoffline\fP は、参照先の生成ドキュメントごとに 1 つずつ指定します。 次の例では、わかりやすくするためにオプションごとに行を分けています。
1178N/A\f2\ \ \ \ \ \ \ \ \ \ \fP\f4\-linkoffline\fP \f2extdocURL2\fP \f2packagelistLoc2\fP \f2\\\fP
1178N/A\f3ドキュメントの更新\fP \- 前述の \f2\-linkoffline\fP オプションのもうひとつの用途は、プロジェクトに大量のパッケージが含まれていて、すでにツリー全体に対して javadoc の実行が完了している場合に、次の実行では、少量の変更を手早く加えたあと、ソースツリーのごく一部に対してだけ javadoc を再実行する場合に便利です。これは、ドキュメンテーションコメントに対してだけ変更を加え、宣言は変更しない場合にのみ正しく処理されるので、ハッキングのようなものです。ソースコードの宣言を追加、削除、または変更した場合は、索引、パッケージツリー、継承されるメンバーのリスト、[使用] ページなどの場所で、リンクが壊れることがあります。
1178N/Aまず、今回の実行で使用する新しい生成先ディレクトリ (\f2update\fP) を作成します。元の生成先ディレクトリの名前が \f2html\fP だとします。もっとも単純な例では、\f2html\fP ディレクトリの親ディレクトリに移動 (cd) します。\f2\-linkoffline\fP の最初の引数にカレントディレクトリ "." を指定し、2 番目の引数に \f2html\fP への相対パスを指定します。 ここで、\f2package\-list\fP が検索されます。 更新対照のパッケージのパッケージ名だけを指定してください。
1178N/A % \fP\f3javadoc \-d update \-linkoffline . html com.mypackage\fP
1178N/AJavadoc ツールの終了後、\f2update/com/package\fP 内の生成されたクラスのページをコピーし (概要や索引を除く)、\f2html/com/package\fP 内の元のファイルに上書きします。
1178N/A各ソースファイル (行番号付き) の HTML バージョンを作成し、標準 HTML ドキュメントからソースファイルへのリンクを追加します。リンクは、ソースファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。デフォルトコンストラクタ、生成されたクラスに対しては作成されません。
1178N/A\f3このオプションは、\fP\f4\-public\fP\f3、\fP\f4\-package\fP\f3、\fP\f4\-protected\fP\f3、\fP\f4\-private\fP\f3 の各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソースファイル内のすべての非公開実装の詳細を公開します。\fP\f2\-private\fP オプションを指定しないかぎり、非公開のクラスやインタフェースの一部には、リンクを介してアクセスできないことがあります。
1178N/A概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。各グループは、それぞれ別の \f2\-group\fP オプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。 各グループ内では、パッケージがアルファベット順に並べられます。指定した \f2\-group\fP オプションごとに、\f2packagepattern\fP 式のリストと一致するパッケージが、見出し \f2groupheading\fP を持つ 1 つの表にまとめて表示されます。
1178N/A\f4packagepattern\fP には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (\f2*\fP) を指定できます。アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして指定できるのは、アスタリスクだけです。1 つのグループには、コロン (\f2:\fP) で区切って複数のパターンを含めることができます。
1178N/A\f3注: パターンやパターンリスト内でアスタリスクを使う場合は、\fP\f4"java.lang*:java.util"\fP\f3 のように、パターンリストを引用符で囲む必要があります。\fP
1178N/A\f2\-group\fP オプションが指定されていない場合は、すべてのパッケージが、「パッケージ」という見出しの 1 つのグループに入れられます。ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という見出しを持つ独立したグループに入れられます。
1178N/Aたとえば、次のようにオプションを指定すると、ドキュメント化される 5 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。「java.lang*」では、最後のドットを指定していないことに注目してください。 「java.lang.*」のようにドットを入れると、java.lang パッケージは除外されることになります。
1178N/A推奨されない API をドキュメントに生成しないようにします。このオプションを指定すると、\-nodeprecatedlist オプションを指定した場合と同じ効果があることに加えて、ドキュメントのほかの部分全体でも、推奨されない API が生成されません。このオプションは、コードを記述しているとき、推奨されないコードによって気を散らされたくない場合に便利です。
1178N/A推奨されない API のリストを含むファイル (deprecated\-list.html)、およびナビゲーションバーのそのページへのリンクが生成されないようにします。ただし、ドキュメントのほかの部分では、推奨されない API が生成されます。このオプションは、推奨されない API がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。
1178N/A生成されるドキュメントからクラスおよびインタフェースの階層ページを省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。デフォルトでは、階層が生成されます。
1178N/A生成されるページの最上部と最下部に表示されるナビゲーションバー、ヘッダー、およびフッターを生成しないようにします。このオプションは、bottom オプションには影響を与えません。\f2\-nonavbar\fP オプションは、印刷するためだけにファイルを PostScript または PDF に変換する場合など、内容だけが重要で、ナビゲーションの必要がない場合に便利です。
1178N/A\-helpfile\ path/filename
1178N/A上部と下部のナビゲーションバーの [ヘルプ] リンクのリンク先となる代替ヘルプファイル \f2path/filename\fP のパスを指定します。このオプションが指定されていない場合、Javadoc ツールは、ハードコードされているヘルプファイル \f2help\-doc.html\fP を自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。\f2filename\fP にはどんなファイル名でも指定でき、\f2help\-doc.html\fP には限定されません。例を示します。
1178N/A\-stylesheetfile\ path/filename
1178N/A代替 HTML スタイルシートファイルのパスを指定します。このオプションが指定されていない場合、Javadoc ツールは、ハードコードされているスタイルシートファイル \f2stylesheet.css\fP を自動的に作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。\f2filename\fP にはどんなファイル名でも指定でき、\f2stylesheet.css\fP には限定されません。例を示します。
1178N/A@serial タグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1.2.2 以降のバージョンでは、直列化の警告は生成されません。1.2.2 より前の初期バージョンでは、警告が生成されます。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと \f2writeExternal\fP メソッドを適切にドキュメント化するのに役立ちます。
1178N/Ahttp://www.iana.org/assignments/character\-sets で与えられた、推奨される MIME 名でなければなりません。例を示します。
1178N/Ahttp://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2 (4197265 および 4137321) を参照してください。
1178N/Ahttp://www.iana.org/assignments/character\-sets で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら \-encoding を使用した場合、生成される HTML ファイルのエンコードは、\-encoding によって決められます。例:
1178N/AHTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。 一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。
1178N/Aメタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。
0N/A <META NAME="keywords" CONTENT="java.lang.String class">
1178N/AJavadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブロックタグ \f2@\fP\f2tagname\fP を解釈できるようにします。これにより、Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内のすべてのカスタムタグに \f2\-tag\fP オプションを組み込むことをお勧めします。今回の実行で出力されないタグは、\f2X\fP を付けて無効にします。
1178N/A\f2\-tag\fP オプションは、タグの見出し「taghead」を太字で出力します。 その次の行には、このオプションの引数で指定したテキストが続きます。 以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。 このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ (\f2@return\fP、\f2@author\fP など) の出力とよく似ています。\f2taghead\fP を省略すると、\f2tagname\fP が見出しとして表示されます。
1178N/A\f3タグの配置\fP \- 引数の \f4Xaoptcmf\fP 部分は、ソースコード内のタグを配置できる位置と、\f2X\fP を使ってこのタグを無効にできるかどうかを特定します。タグの配置位置を制限しない場合は \f4a\fP を指定します。 それ以外の文字の組み合わせも可能です。 \f4X\fP (タグの無効化)
1178N/A上の例の最後のコロン (\f2:\fP) は、パラメータ区切り子ですが、見出しテキストの一部になっています (以下の例を参照)。次の例のように、\f2@todo\fP タグを含むソースコードでは、いずれかのタグオプションを使用します。
1178N/A\f3タグ名にコロンを使用する\fP \- コロン (:) をバックスラッシュでエスケープすると、コロンをタグ名に使用することができます。このドキュメンテーションコメントの中では、次のように使用します。
1178N/A\f3タグ名のスペルチェック (タグの無効化)\fP \- ソースコード内に配置した一部のカスタムタグの出力を抑制したい場合があります。この場合も、ソースコード内にすべてのタグを配置し、出力を抑制しないタグを有効にし、出力を抑制するタグを無効にします。タグを無効にするには、\f2X\fP を指定します。指定しないと、そのタグは有効になります。 これにより、Javadoc ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、Javadoc ツールは警告を出力します。
1178N/Aすでに配置されている値に \f2X\fP を追加できます。 こうしておけば、\f2X\fP を削除するだけでタグを有効にすることができます。たとえば、@todo タグの出力を抑制したい場合、次のように指定します。
1178N/A\f3タグの順序\fP \- \f2\-tag\fP (および \f2\-taglet\fP) オプションの順序によって、その出力順序が決定します。カスタムタグと標準タグを組み合わせて使用することもできます。標準タグのタグオプションは、順序を決定するためだけのプレースホルダです。これらは標準タグ名のみを使用します。(標準タグの小見出しは変更できません。)これについては、以下の例で説明します。
1178N/A\f2\-tag\fP がない場合、\f2\-taglet\fP の位置によってその順序が決定します。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、\f2\-taglet\fP と \f2\-tag\fP の両方が todo という名前を持っている場合、コマンド行の最後にあるほうが順序を決定します。
1178N/A\f3タグの完全セットの例\fP \- この例では、出力の「Parameters」と「Throws」の間に「To Do」を挿入します。X を使用して、@example が、ソースコード内の今回の実行では出力されないタグであることを指定します。@argfile を使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます。 行の継続を示す文字は不要です。
1178N/Ajavadoc がドキュメンテーションコメントを解析する際に検出されたタグのうち、標準タグでも \f2\-tag\fP や \f2\-taglet\fP で渡されるタグでもないものは、未知のタグの見なされます。 この場合、警告がスローされます。
1178N/A標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。\f2\-tag\fP オプションを使用すると、このリストに追加されるタグ、すなわち標準タグの位置がデフォルトの位置から移動します。つまり、標準タグに \f2\-tag\fP オプションを付けなければ、これらはデフォルトの位置に配置されたままになります。
1178N/A\f3競合の回避\fP \- 固有の名前空間を分割するには、パッケージに使用されている \f2com.mycompany.todo\fP のように、ドット (.) 区切りの命名規則を使用します。Sun は、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Sun が提供する同じ名前のタグの動作をオーバーライドします。つまり、ユーザーが \f2@todo\fP という名前のタグまたはタグレットを作成している場合、Sun があとから同じ名前の標準タグを作成しても、そのタグまたはタグレットは元の動作を保持します。
1178N/A\f3注釈 vs. Javadoc タグ\fP \- 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。 それ以外の場合は注釈にすべきです。
1178N/Ahttp://java.sun.com/j2se/javadoc/writingdoccomments/index.html#annotationsを参照してください。
1178N/Aそのタグのドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。クラスの完全指定名を指定してください。このタグレットは、カスタムタグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。外部ドキュメントとサンプルタグレットについては、以下を参照してください。
1178N/Aタグレットは、標準タグまたはインラインタグで便利です。タグレットは任意の数の引数をとることができます。 また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。
1178N/Aタグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。
1178N/Aタグレットのパスを指定するには、\f2\-tagletpath\fP オプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。
1178N/A \-taglet com.sun.tools.doclets.ToDoTaglet
1178N/A \-tagletpath /home/taglets
1178N/A\f2\-tag\fP オプションの代わりに \f2\-taglet\fP オプションを使用することもできますが、読みやすさを考慮するなら、\f2\-tag\fP オプションを使用したほうがよいでしょう。
1178N/Ataglet クラスファイル (.class) の検索パスを指定します。\f2tagletpathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパスの以下すべてのサブディレクトリを検索します。
1178N/A\f2doc\-files\fP ディレクトリの深いコピーを有効にします。つまり、コピー先には、サブディレクトリとすべてのコンテンツがコピーされます。たとえば、\f2doc\-files/example/images\fP ディレクトリとその中のファイルがコピーされます。ここでも、サブディレクトリを除外する指定が可能です。
1178N/A出力されるクラス名の先頭のパッケージ名 (パッケージ修飾子) を省略します。\f2\-noqualifier\fP の引数として \f2all\fP を指定した場合、すべてのパッケージ修飾子がすべて省略されます。 削除する複数のパッケージ名をコロンで区切って、ワイルドカードとともに指定することもできます。クラスまたはインタフェース名が表示される位置からパッケージ名が削除されます。
1178N/Aパッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。 詳細は「名前の表示方法」を参照してください。この規則は、\f2\-noqualifier\fP を使用したかどうかにかかわらず有効です。
1178N/Aタイムスタンプが抑制されます。 各ページ先頭近くにある、生成された HTML 内の HTML コメントでタイムスタンプが隠されます。Javadoc を 2 つのソースベースで実行し、それらに対して diff を実行するときにこのオプションを使用すると、タイムスタンプによって diff が発生しなくなるので便利です (このオプションを使用しないと、各ページで diff になります)。タイムスタンプには Javadoc のバージョン番号が含まれており、次のようになります。
1178N/A主説明およびすべてのタグを含むコメント本文全体を抑制し、宣言だけを生成します。このオプションにより、元は異なる目的のためだったソースファイルを再利用し、新しいプロジェクトの早い段階でスケルトン HTML ドキュメントを作成できるようになりました。
1178N/A\f2javadoc\fP のコマンド行を短くしたり簡潔にしたりするために、\f2javadoc\fP コマンドに対する引数 (\f2\-J\fP オプションを除く) が入った 1 つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティングシステム上でも、任意の長さの javadoc コマンドを作成できます。
1178N/A引数ファイルには、javac のオプションとソースファイル名を自由に組み合わせて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲みます。
1178N/A引数ファイル内のファイル名は、現在のディレクトリから見た相対パスになります。引数ファイルの位置から見た相対パスではありません。引数ファイル内のファイル名リストでは、ワイルドカード (*) は使用できません。たとえば、\f2*.java\fP とは指定できません。引数ファイル内の引数で \f2@\fP 文字を使用して、複数のファイルを再帰的に解釈することはサポートされていません。また、\f2\-J\fP オプションもサポートされていません。 このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。
1178N/Ajavadoc を実行するときに、各引数ファイルのパスとファイル名の先頭に \f2@\fP 文字を付けて渡します。javadoc は、\f2@\fP 文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。
1178N/AJavadoc オプション用に 1 つ、ソースファイル名用に 1 つというように、2 つの引数ファイルを作成し、次のようにして使用することができます。なお、このあとのリストでは、行の継続文字を使用していません。
1178N/A引数ファイルには、パスを指定できます。 ただし、そのファイル内に指定されたファイル名は、現在の作業ディレクトリから見た相対パスになります。 つまり、下の例の場合は、\f2path1\fP や \f2path2\fP から見た相対パスではありません。
1178N/A次に、Javadoc オプションに対する引数だけを引数ファイルに格納する例を示します。ここでは、\f2\-bottom\fP を例に取り上げます。 そのオプションには、かなり長い引数を指定することがあるからです。まず、このオプションのテキスト引数になる次のような内容を含む、\f2bottom\fP という名前のファイルを作成します。
1178N/A'<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit a
1178N/A\f3バージョン番号\fP \- javadoc のバージョン番号を判別するには、\f3javadoc \-J\-version\fP を使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。\f2\-quiet\fP で無効にできます。
1178N/A\f3公開プログラムインタフェース\fP \- Java 言語で記述されたプログラムから Javadoc ツールを起動するとき使用します。このインタフェースは \f2com.sun.tools.javadoc.Main\fP にあります (javadoc は再入可能)。詳細は、
1178N/Ahttp://java.sun.com/javase/6/docs/technotes/guides/javadoc/standard\-doclet.html#runningprogrammaticallyを参照してください。
1178N/A\f3ドックレットの実行\fP \- 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、\-doclet および \-docletpath オプションを使用します。特定のドックレットを実行した完全な例については、
1178N/Ajavadoc は、パッケージ全体に対して実行することも、個々のソースファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。次の例では、ソースファイルは \f2/home/src/java/awt/*.java\fP にあります。生成先ディレクトリは \f2/home/html\fP です。
1178N/Aパッケージをドキュメント化するには、そのパッケージのソースファイル (\f2*.java\fP) が、パッケージと同じ名前を持つディレクトリ内に存在していなければなりません。パッケージ名が複数の識別子で構成されている (\f2java.awt.color\fP のように、各識別子はドットで区切られている) 場合は、後続の各識別子が下位のサブディレクトリに対応していなければなりません (\f2java/awt/color\fP など)。1 つのパッケージのための複数のソースファイルを、異なる場所にある 2 つのディレクトリツリーに分けて格納することも可能です (\f2src1/java/awt/color\fP と \f2src2/java/awt/color\fP など)。 ただし、その場合は、\f2\-sourcepath\fP によって、その両方の場所を指定しなければなりません。
1178N/Ajavadoc を実行するには、\f2cd\fP コマンドを使ってディレクトリを変更するか、または \f2\-sourcepath\fP オプションを使用します。以下の例では、両方の方法について説明します。
1178N/A\f3ケース 1 \- 1 つ以上のパッケージからの起動を再帰的に実行\fP \- この例では javadoc が任意のディレクトリから実行できるように、\-sourcepath を使用し、再帰的処理のために \-subpackages (1.4 の新オプション) を使用します。これは、\f2java\fP のサブパッケージ (\f2java.net\fP および \f2java.lang\fP をルートとするパッケージを除く) を処理します。ただし、\f2java.lang\fP のサブパッケージである \f2java.lang.ref\fP は除外されます。
1178N/A % \fP\f3javadoc \fP\f3\-d\fP\f3 /home/html \fP\f3\-sourcepath\fP\f3 /home/src \fP\f3\-subpackages\fP\f3 java \fP\f3\-exclude\fP\f3 java.net:java.lang\fP
1178N/Aその他のパッケージツリーを巡回するには、\f2java:javax:org.xml.sax\fP のように、\f2\-subpackages\fP 引数にその名前を追加します。
1178N/A\f3ケース 2 \- ルートソースディレクトリに移ってから明示的なパッケージに対して実行\fP \- 完全指定のパッケージ名の親ディレクトリに移ります。次に、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。
1178N/A\f3ケース 3 \- 任意のディレクトリから実行。 ソースファイルは 1 つのディレクトリツリー内にある\fP \- このケースでは、現在のディレクトリがどこであってもかまいません。最上位パッケージの親ディレクトリを \f2\-sourcepath\fP に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。
1178N/A\f3ケース 4 \- 任意のディレクトリから実行。 ソースファイルは複数のディレクトリツリー内にある\fP \- これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに存在します。それぞれのツリーのルートへのパスを \f2\-sourcepath\fP に指定し (コロンで区切る)、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。1 つのパッケージのすべてのソースファイルが、1 つのルートディレクトリの下に存在しなければならない、ということはありません。 ソースパスとして指定された場所のどこかで見つかれば十分です。
1178N/A % \fP\f3javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java.awt java.awt.event\fP
1178N/A結果: 上記のどのケースでも、\f2java.awt\fP と \f2java.awt.event\fP パッケージ内の public および protected クラスとインタフェースについて、HTML 形式のドキュメントが生成され、指定された生成先ディレクトリ (\f2/home/html\fP) に HTML ファイルが保存されます。2 つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラスページという 3 つのフレームを持つことになります。
1178N/Aまた、1 つ以上のソースファイル (\f2.java\fP) を渡して、Javadoc ツールを実行することもできます。javadoc は、次の 2 つのどちらかの方法で実行できます。 1 つは、\f2cd\fP コマンドでディレクトリを変更する方法、もう 1 つは \f2.java\fP ファイルへのパスを完全指定する方法です。相対パスは、現在のディレクトリを起点とします。ソースファイル名を渡すときは、\f2\-sourcepath\fP オプションは無視されます。アスタリスク (*) のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。
1178N/A\f3ケース 1 \- ソースディレクトリに移る\fP \- \f2.java\fP ファイルのあるディレクトリに移ります。次に、ドキュメント化する 1 つ以上のソースファイルの名前を指定して javadoc を実行します。
1178N/A % \fP\f3cd /home/src/java/awt\fP
1178N/Aこの例では、クラス \f2Button\fP と \f2Canvas\fP、および名前が \f2Graphics\fP で始まるクラスについて、HTML 形式のドキュメントが生成されます。パッケージ名ではなくソースファイルが javadoc に引数として渡されているので、ドキュメントは、クラスのリストとメインページという 2 つのフレームを持つことになります。
1178N/A\f3ケース 2 \- パッケージのルートディレクトリに移る\fP \- これは、同じルート内にある複数のサブパッケージの個々のソースファイルをドキュメント化する場合に便利です。パッケージのルートディレクトリに移り、各ソースファイルを、ルートからのパスとともに指定します。
1178N/A\f3ケース 3 \- 任意のディレクトリから\fP \- このケースでは、現在のディレクトリがどこであってもかまいません。ドキュメント化する \f2.java\fP ファイルへの絶対パス (または、現在のディレクトリからの相対パス) を指定して javadoc を実行します。
1178N/A % \fP\f3javadoc \-d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java\fP
1178N/Aパッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に前述の 2 つの例を組み合わせた例を示します。\f2\-sourcepath\fP は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。
1178N/A % \fP\f3javadoc \-d /home/html \-sourcepath /home/src java.awt /home/src/java/applet/Applet.java\fP
1178N/Aこの例では、パッケージ \f2java.awt\fP と、クラス \f2Applet\fP について、HTML 形式のドキュメントが生成されます。Javadoc ツールは、\f2Applet\fP のパッケージ名を、\f2Applet.java\fP ソースファイル内のパッケージ宣言 (その宣言がある場合) から判別します。
1178N/AJavadoc ツールには多くの便利なオプションがあり、その中にはほかのオプションよりも頻繁に使われるものがあります。ここで紹介するのは、Java プラットフォーム API に対して Javadoc ツールを実行するときに使用する実際のコマンドです。Java 2 Platform, Standard Edition, v1.2 に存在する、約 1500 個の public および protected クラスについてドキュメントを生成するために、180M バイトのメモリーを使用しました。
1178N/A同じ例を 2 回掲載します。 最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。オプションの引数に絶対パスを使用しているため、任意のディレクトリからこの \f2javadoc\fP コマンドを実行できます。
1178N/A次のコマンド行の例は 900 文字を超えているため、DOS などのシェルには大きすぎます。この制限を回避するには、コマンド行引数ファイルを使用します。 または、シェルスクリプトを記述します。
1178N/A% javadoc \-sourcepath /java/jdk/src/share/classes \\
1178N/A \-overview /java/jdk/src/share/classes/overview.html \\
1178N/A \-d /java/jdk/build/api \\
0N/A \-bottom '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit
1178N/A上記のコマンドで、\f2packages\fP は、処理対象のパッケージ名 (\f2java.applet java.lang\fP など) が入っているファイルの名前です。各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー＆ペーストする場合は、\f2\-bottom\fP オプションから改行文字を削除してください。さらに、このあとの「注」も参照してください。
1178N/Ahttp://java.sun.com/j2se/javadoc/faq/index.html#makefilesを参照してください。
0N/A \-\fP\f3overview\fP\f3 $(SRCDIR)/overview.html \\ /* Sets file for overview text */
0N/A \-\fP\f3d\fP\f3 /java/jdk/build/api \\ /* Sets destination directory */
0N/ABOTTOM = '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit
1178N/A\f2\-windowtitle\fP オプションを省略すると、Javadoc ツールによって、ドキュメントタイトルがウィンドウタイトルにコピーされます。\f2\-windowtitle\fP のテキストは、基本的に \f2\-doctitle\fP と同じです。 ただし、HTML タグは使用しません。 HTML タグは、ウィンドウタイトルにそのままのテキストとして表示されてしまいます。
1178N/A\f3有効なクラスだけをドキュメント化\fP \- パッケージをドキュメント化するとき、Javadoc は、有効なクラス名で構成されているファイルのみを読み込みます。たとえば、ファイル名にハイフン「\-」を含めることで、javadoc によるファイルの解析を防ぐことができます。
1178N/A\f2"error:cannot read:Class1.java"\fP Javadoc ツールはカレントディレクトリに Class1.java クラスをロードしようとしています。絶対パスまたは相対パスとともに表示されるクラス名は、この例の場合 \f2./Class1.java\fP と同じです。