1 ." Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved. 2 ." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 ." 4 ." This code is free software; you can redistribute it and/or modify it 5 ." under the terms of the GNU General Public License version 2 only, as 6 ." published by the Free Software Foundation. 7 ." 8 ." This code is distributed in the hope that it will be useful, but WITHOUT 9 ." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 10 ." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 11 ." version 2 for more details (a copy is included in the LICENSE file that 12 ." accompanied this code). 13 ." 14 ." You should have received a copy of the GNU General Public License version 15 ." 2 along with this work; if not, write to the Free Software Foundation, 16 ." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 17 ." 18 ." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 19 ." or visit www.oracle.com if you need additional information or have any 20 ." questions. 21 ." 22 .TH javadoc 1 "07 May 2011" 23 .SH "名前" 24 javadoc \- Java API ドキュメントジェネレータ 25 .LP 26 Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、 Solaris を使用した場合のものです。 27 .SH "形式" 28 .LP 29 \f4javadoc\fP\f2\ [\ \fP\f2options\fP\f2\ ]\ [\ packagenames\ ]\ [\ sourcefilenames\ ]\ [\ \-subpackages\fP\ \f2pkg1:pkg2:...\fP\f2\ ]\ [\ \fP\f2@argfiles\fP\f2\ ]\fP 30 .LP 31 引数を指定する順序は任意です。Javadoc ツールでの、処理対象の .java ファイルを決定する方法の詳細については、「ソースファイルの処理」\f2を参照\fPしてください。 32 .RS 3 33 .TP 3 34 options 35 このドキュメントで説明されているコマンド行オプションです。Javadoc オプションの標準的な使用法については、「使用例」を参照してください。 36 .TP 3 37 packagenames 38 スペースで区切られた一連のパッケージ名です。たとえば、 \f2java.lang\ java.lang.reflect\ java.awt のように指定します\fP。ドキュメント化するパッケージを個別に指定する必要があります。ワイルドカードは使用不可です。再帰的処理のためには、\-subpackages を使用します。Javadoc ツールは、\f2\-sourcepath\fP を使用してこれらのパッケージ名を検索します。「1 つ以上のパッケージのドキュメント化」の例を参照してください。 39 .TP 3 40 sourcefilenames 41 スペースで区切られた一連のソースファイル名です。 各ファイルは、パスで始まります。アスタリスク (*) などのワイルドカードを含めることができます。Javadoc ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、その拡張子を除いた名前が実際に有効なクラス名であるすべてのファイルです (Java 言語仕様を参照)。したがって、ハイフンを含む名前 ( \f2X\-Buffer\fP など) や、その他の無効な文字を含む名前を付けることによって、それらのファイルをドキュメント化の対象から除外できます。これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。ソースファイル名の前に指定したパスによって、javadoc がそのファイルを検索する場所が決まります。Javadoc ツールは、これらのソースファイル名を検索するときには \f2\-sourcepath\fP を使用しません。相対パスは現在のディレクトリを起点とするため、 \f2Button.java\fP を渡すことは、 \f2./Button.java\fP を渡すことと同じです。ソースファイル名をフルパスで指定すると、 \f2/home/src/java/awt/Graphics*.java のようになります\fP。 「1 つ以上のクラスのドキュメント化」の例を参照してください。また、「パッケージとクラスのドキュメント化」の例のように、パッケージ名とソースファイル名を混在させることもできます。 42 .TP 3 43 \-subpackages pkg1:pkg2:... 44 ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。パッケージ名またはソースファイル名を指定する必要はありません。 45 .TP 3 46 @argfiles 47 Javadoc オプション、パッケージ名、およびソースファイル名を任意の順序で並べたリストが含まれる 1 つ以上のファイルです。ワイルドカード (*) や \f2\-J\fP オプションは、このファイルの中では指定できません。 48 .RE 49 .SH " 説明" 50 .LP 51 \f3Javadoc\fP ツールは、一連の Java ソースファイルにある宣言およびドキュメンテーションコメントを解析し、デフォルトでは public クラス、protected クラス、入れ子にされたクラス (匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。 52 .LP 53 Javadoc ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して実行できます。パッケージ全体のドキュメント化を行うには、\f2\-subpackages\fP を使用して最上位ディレクトリから下方に再帰的にたどるか、パッケージ名の明示的なリストを渡します。個々ソースファイルに対して javadoc を実行する場合は、一連のソース (.\f2.java\fP) ファイル名を渡します。具体的な例は、このドキュメントの最後に紹介します。次に、Javadoc によるソースファイルの処理について説明します。 54 .SS 55 ソースファイルの処理 56 .LP 57 Javadoc ツールは、末尾が「\f2.java\fP」のファイルを処理するだけでなく、「ソースファイル」で説明するその他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、どの \f2.java\fP ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。その方法とは、(1) パッケージ名を渡す、(2) \f2\-subpackages\fP を使用する、(3) ソースファイル名でワイルドカードを使用する (\f2*.java\fP)、の 3 つです。これらの場合、Javadoc ツールが「\f2.java\fP」ファイルの処理を行うのは、そのファイルが次のすべての要件を満たす場合だけです。 58 .RS 3 59 .TP 2 60 o 61 名前から接尾辞「\f2.java\fP」を取り除くと、実際に有効なクラス名になっている (Java 言語仕様の有効な文字を参照) 62 .TP 2 63 o 64 ソースツリーのルートから相対的なディレクトリパスが、区切り文字をドットに変換すると、実際に有効なパッケージ名になっている 65 .TP 2 66 o 67 パッケージ文には有効なパッケージ名が含まれる (前項目で指定) 68 .RE 69 .LP 70 \f3リンクの処理\fP \- Javadoc ツールは、処理の実行中に、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、自動的に相互参照リンクを追加します。このようなリンクは、次のような場所に追加されます。 71 .RS 3 72 .TP 2 73 o 74 宣言 (戻り値の型、引数の型、フィールドの型) 75 .TP 2 76 o 77 \f2@see\fP タグから生成された [関連項目] セクション 78 .TP 2 79 o 80 \f2{@link}\fP タグから生成されたインラインテキスト 81 .TP 2 82 o 83 \f2@throws\fP タグから生成された例外の名前 84 .TP 2 85 o 86 インタフェースのメンバーに対する「定義」リンクと、クラスのメンバーに対する「オーバーライド」リンク 87 .TP 2 88 o 89 パッケージ、クラス、およびメンバーを列挙している概要テーブル 90 .TP 2 91 o 92 パッケージおよびクラスの継承ツリー 93 .TP 2 94 o 95 索引 96 .RE 97 .LP 98 コマンド行で指定しなかったクラスについての既存のテキスト (別に生成したテキスト) に対してハイパーリンクを追加するには、\f2\-link\fP および \f2\-linkoffline\fP オプションを利用できます。 99 .LP 100 \f3その他の処理についての詳細\fP \- Javadoc ツールは、実行するたびに 1 つの完全なドキュメントを作成します。ドキュメントを追加生成することはできません。つまり、Javadoc ツールの以前の実行結果を修正したり、その内容を直接組み入れたりすることはできません。ただし、前述のように、以前の実行結果に対してリンクを追加することはできます。 101 .LP 102 実装上の理由から、Javadoc ツールは、処理を実行するために java コンパイラを必要とし、java コンパイラに依存しています。Javadoc ツールは、 \f2javac\fP の一部を呼び出して宣言をコンパイルしますが、メンバーの実装は無視します。Javadoc ツールは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、その情報から HTML を生成します。さらに、Javadoc ツールは、ソースコードのドキュメンテーションコメントから、ユーザーの提供したドキュメントも取得します。 103 .LP 104 実際には、Javadoc ツールは、メソッド本体を持たない純粋なスタブファイルであるような \f2.java\fP ソースファイルでも動作します。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc ツールを実行できます。 105 .LP 106 コンパイラに依存することによって、HTML 出力は、実際の実装に正確に対応します。実際の実装は、明示的なソースコードにではなく、暗黙のソースコードに依存する場合があります。たとえば、Javadoc ツールは、.class ファイルには存在するがソースコードには存在しないデフォルトコンストラクタ (Java 言語仕様を参照) \f2をドキュメント化\fP します。 107 .LP 108 通常、Javadoc ツールでは、ソースファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。このため、デバッグやトラブルシューティングを完了する前にドキュメントを生成できます。たとえば、Java 言語仕様によると、抽象メソッドを含むクラスは、それ自体抽象として宣言されなければなりません。このエラーを検出すると、javac コンパイラは停止しますが、Javadoc ツールは警告を出さずに処理を続行します。Javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、DocCheck ドックレットを使用してください。 109 .LP 110 Javadoc ツールは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、Javadoc ツールは、ブートストラップクラス、拡張機能、またはユーザークラスにかかわらず、すべての参照クラスを検索できなければなりません。詳細は、 111 .na 112 \f2「クラスの検索方法」\fP @ 113 .fi 114 http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.htmlを参照してください。通常、作成するクラスは、拡張機能としてロードするか、Javadoc ツールのクラスパス内に置く必要があります。 115 .SS 116 Javadoc のドックレット 117 .LP 118 Javadoc ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。Javadoc ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み」ドックレットがあります。標準ドックレットは、HTML 形式の API ドキュメントを生成します。標準ドックレットを修正またはサブクラス化することや、HTML、XML、MIF、RTF などの好みの出力形式を生成する独自のドックレットを記述することも可能です。ドックレットとその使用法については、次の項目を参照してください。 119 .RS 3 120 .TP 2 121 o 122 .na 123 \f2Javadoc のドックレット\fP @ 124 .fi 125 http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html 126 .TP 2 127 o 128 \f2\-doclet\fP コマンド行オプション 129 .RE 130 .LP 131 \f2\-doclet\fP コマンド行オプションでカスタムドックレットが指定されていない場合、Javadoc ツールは、デフォルトの標準ドックレットを使用します。javadoc ツールには、使用されているドックレットに関係なく使用できるコマンド行オプションがあります。標準ドックレットでは、これらのほかに、いくつかのコマンド行オプションが追加されます。どちらのオプションについても、このあとの「オプション」で説明します。 132 .SS 133 関連ドキュメントおよびドックレット 134 .RS 3 135 .TP 2 136 o 137 .na 138 \f2Javadoc に施された拡張機能\fP @ 139 .fi 140 http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html \- Javadoc 1.4 で追加された改良点の詳細 141 .TP 2 142 o 143 .na 144 \f2Javadoc FAQ\fP @ 145 .fi 146 http://java.sun.com/j2se/javadoc/faq/index.html \- 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法 147 .TP 2 148 o 149 .na 150 \f2How to Write Doc Comments for Javadoc\fP @ 151 .fi 152 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html \- ドキュメンテーションコメントの記述方法に関する Sun の規約 153 .TP 2 154 o 155 .na 156 \f2Requirements for Writing API Specifications\fP @ 157 .fi 158 http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Java SE プラットフォーム仕様を記述する際に使用された標準要件この情報は、ソースファイルのドキュメンテーションコメント形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも役立ちます。検証可能なアサーションを満たすパッケージ、クラス、インタフェース、フィールド、およびメソッドについての要件を定めています。 159 .TP 2 160 o 161 .na 162 \f2ドキュメンテーションコメントの仕様\fP @ 163 .fi 164 http://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 版では削除されました。 165 .TP 2 166 o 167 .na 168 \f2DocCheck ドックレット\fP @ 169 .fi 170 http://www.oracle.com/technetwork/java/javase/documentation/index\-141437.html \- ソースファイル内のドキュメンテーションコメントをチェックし、検出されたエラーや不正のレポートを生成します。Doc Check ユーティリティーの一部です。 171 .TP 2 172 o 173 .na 174 \f2MIF ドックレット\fP @ 175 .fi 176 http://java.sun.com/j2se/javadoc/mifdoclet/ \- MIF、FrameMaker、PDF の書式で API ドキュメントを自動生成します。MIF は Adobe FrameMaker の交換書式です。 177 .RE 178 .SS 179 用語 180 .LP 181 \f2「ドキュメンテーションコメント」\fP、\f2「doc コメント」\fP、\f2「主説明」\fP、\f2「タグ」\fP、\f2「ブロックタグ」\fP、および\f2「インラインタグ」\fPの用語については、「ドキュメンテーションコメント」で説明します以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。 182 .RS 3 183 .TP 3 184 生成ドキュメント (generated document) 185 javadoc ツールが Java ソースコード内のドキュメンテーションコメントから生成したドキュメントのことです。デフォルトの生成ドキュメントは HTML 形式で、標準ドックレットによって作成されます。 186 .LP 187 .TP 3 188 名前 (name) 189 Java 言語で書かれたプログラム要素の名前、つまりパッケージ、クラス、インタフェース、フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、 \f2java.lang.String.equals(java.lang.Object)\fP のような完全修飾名にすることも、 \f2equals(Object)\fP のような部分修飾名にすることもできます。 190 .LP 191 .TP 3 192 ドキュメント化されるクラス (documented classes) 193 javadoc ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。ドキュメント化するには、ソースファイルが使用可能でなければならず、ソースファイル名またはパッケージ名を javadoc コマンドに渡され、アクセス修飾子 (public、protected、package\-private または private) によってフィルタ処理されないようにしなければなりません。ドキュメント化されるクラスは、javadoc ツールの出力に組み込まれるクラス、つまり「包含クラス」とも呼ばれます。 194 .LP 195 .TP 3 196 包含クラス (included classes) 197 ツールの実行によって詳細なドキュメントが生成されるクラスおよびインタフェースのことです。「ドキュメント化されるクラス」と同じ。 198 .LP 199 .TP 3 200 除外クラス (excluded classes) 201 ツールの実行によって詳細なドキュメントが生成されないクラスおよびインタフェースのことです。 202 .LP 203 .TP 3 204 参照クラス (referenced classes) 205 ドキュメント化されるクラスおよびインタフェースの定義 (実装) またはドキュメンテーションコメントの中で明示的に参照されているクラスおよびインタフェースのことです。参照の例としては、戻り値の型、パラメータの型、キャストの型、拡張されたクラス、実装されたインタフェース、インポートされたクラス、メソッド本体で使用されるクラス、@see、{@link}、{@linkplain}、{@inheritDoc} タグなどがあります。この定義は 206 .na 207 \f21.3\fP @ 208 .fi 209 http://download.oracle.com/javase/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses から変更されています。javadoc ツールを実行するときは、Javadoc のブートクラスパスおよびクラスパス内にあるすべての参照クラスをメモリーにロードする必要があります。参照クラスが見つからない場合は、「クラスが見つかりません」という警告が表示されます。Javadoc ツールは、クラスの存在とそのメンバーの完全指定の名前を判別するのに必要なすべての情報を、.class ファイルから引き出すことができます。 210 .LP 211 .TP 3 212 外部参照クラス (external referenced classes) 213 参照クラスのうち、javadoc ツールの実行中にドキュメントが生成されないクラスのことです。つまり、これらのクラスは、コマンド行で Javadoc ツールに渡されていません。生成ドキュメント内でこれらのクラスにリンクしている箇所は、「外部参照」または「外部リンク」と呼ばれます。たとえば、Javadoc ツールの実行対象が \f2java.awt\fP パッケージのみである場合、 \f2java.lang\fP 内のすべてのクラス ( \f2Object\fPなど) が外部参照クラスになります。外部参照クラスにリンクするには、 \f2\-link\fP および \f2\-linkoffline\fP オプションを使用します。外部参照クラスには、通常そのソースコメントを javadoc ツールの実行で利用できないという重要な特徴があります。この場合、それらのコメントを継承することはできません。 214 .RE 215 .SH "ソースファイル" 216 .LP 217 Javadoc ツールは 4 種類の異なる「ソース」ファイルから出力を生成します。その 4 種類とは、クラスの Java 言語ソースファイル (\f2.java\fP)、パッケージコメントファイル、概要コメントファイル、およびその他の処理されないファイルです。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートファイルについても説明します。 218 .SS 219 クラスソースコードファイル 220 .LP 221 それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーションコメントを持つことができ、それを \f2.java\fP ファイル内に保持します。ドキュメンテーションコメントの詳細は、「ドキュメンテーションコメント」を参照してください。 222 .SS 223 パッケージコメントファイル 224 .LP 225 それぞれのパッケージは、独自のドキュメンテーションコメントを持つことができ、それを専用の「ソース」ファイルに保持します。その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。 226 .LP 227 パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。 228 .RS 3 229 .TP 2 230 o 231 \f2package\-info.java\fP \- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは一般に、package.html よりも推奨されます。 232 .TP 2 233 o 234 \f2package.html\fP \- 格納できるのはパッケージコメントと Javadoc タグだけです。パッケージ注釈は格納できません。 235 .RE 236 .LP 237 各パッケージでは、単一の \f2package.html\fP ファイル、単一の \f2package\-info.java\fP ファイルのいずれかを選択できますが、その両方を選択することはできません。このどちらかのファイルを \f2.java\fP ファイルとともに、ソースツリー内のそのパッケージのディレクトリ内に配置してください。 238 .LP 239 \f4package\-info.java\fP \- このファイルには、次の構造のパッケージコメントを格納できます。 コメントはパッケージ宣言の前に配置します。 240 .LP 241 File: \f2java/applet/package\-info.java\fP 242 .nf 243 \f3 244 .fl 245 /** 246 .fl 247 * Provides the classes necessary to create an 248 .fl 249 * applet and the classes an applet uses 250 .fl 251 * to communicate with its applet context. 252 .fl 253 * <p> 254 .fl 255 * The applet framework involves two entities: 256 .fl 257 * the applet and the applet context. 258 .fl 259 * An applet is an embeddable window (see the 260 .fl 261 * {@link java.awt.Panel} class) with a few extra 262 .fl 263 * methods that the applet context can use to 264 .fl 265 * initialize, start, and stop the applet. 266 .fl 267 * 268 .fl 269 * @since 1.0 270 .fl 271 * @see java.awt 272 .fl 273 */ 274 .fl 275 package java.lang.applet; 276 .fl 277 \fP 278 .fi 279 .LP 280 コメント区切り文字の \f2/**\fP と \f2/*\fP は存在している必要がありますが、中間行の行頭のアスタリスクは省略してもかまいません。 281 .LP 282 \f4package.html\fP \- このファイルには、次の構造のパッケージコメントを格納できます。コメントは \f2<body>\fP 要素内に配置します。 283 .LP 284 File: \f2java/applet/package.html\fP 285 .nf 286 \f3 287 .fl 288 <HTML> <BODY> Provides the classes necessary to create an applet and the classes an applet uses to communicate with its applet context.<p> 289 .fl 290 The applet framework involves two entities: the applet 291 .fl 292 and the applet context. An applet is an embeddable window (see the {@link java.awt.Panel} class) with a few extra methods that the applet context can use to initialize, start, and stop the applet.@since 1.0 @see java.awt </BODY> </HTML> 293 .fl 294 \fP 295 .fi 296 .LP 297 これは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述しますが、1 つだけ例外があります。それは、このドキュメンテーションコメントには、コメント区切り文字 である \f2/**\fP と \f2*/\fP 、および行頭のアスタリスクを含めてはならない、という点です。コメントを書く場合は、最初の文をパッケージの概要とし、 \f2<body>\fP と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、すべてのブロックタグは、主説明のあとに置かなければなりません。 \f2@see\fP タグをパッケージコメントファイルに追加する場合には、完全修飾名を使用する必要があります。詳細は、 298 .na 299 \f2package.html\fPの例 @ 300 .fi 301 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#packagecommentsを参照してください。 302 .LP 303 \f3パッケージコメントファイルの処理\fP \- Javadoc ツールは、実行時にパッケージコメントファイルを自動的に検索し、このファイルを見つけると次の処理を行います。 304 .RS 3 305 .TP 2 306 o 307 処理できるようにコメントをコピーする( \f2package.html\fP の場合であれば、 \f2<body>\fP と \f2</body>\fP HTML タグの間にある内容をすべてコピーする。 \f2<head>\fP セクションを含め、そこに \f2<title>\fP やソースファイルの著作権記述などの情報を配置することもできるが、生成後のドキュメンテーションにはそれらは一切表示されない) 308 .TP 2 309 o 310 パッケージタグがあれば、すべて処理する 311 .TP 2 312 o 313 生成したパッケージの概要ページの最後に、処理したテキストを挿入する (例: 314 .na 315 \f2パッケージの概要\fP @ 316 .fi 317 http://java.sun.com/javase/6/docs/api/java/applet/package\-summary.html) 318 .TP 2 319 o 320 パッケージの概要ページの先頭に、パッケージコメントの最初の文をコピーする。さらに、概要ページのパッケージリストに、パッケージ名とパッケージコメントの最初の文を追加する (例: 321 .na 322 \f2概要の要約\fP @ 323 .fi 324 http://java.sun.com/javase/6/docs/api/overview\-summary.html)。文の末尾は、クラスやメンバーの主説明の最初の文の末尾と同じ規則によって判断される 325 .RE 326 .SS 327 概要コメントファイル 328 .LP 329 ドキュメント化する各アプリケーションまたはパッケージセットは、独自の概要ドキュメンテーションコメントを持つことができ、それは専用の「ソース」ファイルに保持されます。その内容は、Javadoc ツールによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージセット全体に当てはまるドキュメントを記述します。 330 .LP 331 概要コメントファイルを作成するには、ファイルに任意の名前 (通常は \f4overview.html\fP) を付け、それを任意の場所 (通常はソースツリーの最上位) に配置できます。たとえば、 \f2java.applet\fP パッケージのソースファイルが \f2/home/user/src/java/applet\fP ディレクトリに格納されていれば、概要コメントファイルは \f2/home/user/src/overview.html に作成できます\fP。 332 .LP 333 異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。たとえば、内部ドキュメンテーション用に \-private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。 334 .LP 335 概要コメントファイルの内容は、前述のパッケージコメントファイルと同様、HTML で記述された 1 つの大きなドキュメンテーションコメントです。詳細は、前述の説明を参照してください。要点を繰り返すと、このコメントを記述する場合は、最初の文をアプリケーションまたはパッケージセットの要約とし、 \f2<body>\fP と最初の文の間にタイトルその他のテキストを含めないようにします。概要タグを含めることができます。ほかのドキュメンテーションコメントと同じく、 \f2{@link}\fP などのインラインタグを除くすべてのタグは、主説明のあとに配置する必要があります。 \f2@see\fP タグを追加する場合には、完全修飾名を使用する必要があります。 336 .LP 337 Javadoc ツールの実行時に、\-overview オプションを使って概要コメントファイル名を指定します。このファイルは、パッケージコメントファイルと同じように処理されます。 338 .RS 3 339 .TP 2 340 o 341 \f2<body>\fP と \f2</body>\fP タグの間にあるすべての内容を処理対象としてコピーする 342 .TP 2 343 o 344 概要タグがあれば、すべて処理する 345 .TP 2 346 o 347 生成した概要ページの最後に、処理したテキストを挿入する (例: 348 .na 349 \f2概要の要約\fP @ 350 .fi 351 http://java.sun.com/javase/6/docs/api/overview\-summary.html) 352 .TP 2 353 o 354 概要ページの先頭に、概要コメントの最初の文をコピーする 355 .RE 356 .SS 357 その他の未処理のファイル 358 .LP 359 ソースには、Javadoc ツールによって生成先のディレクトリにコピーされる、その他の任意のファイルを含めることができます。一般に、このようなファイルには、グラフィックファイル、サンプルの Java ソース (.java) およびクラス (.class) ファイル、内容が通常の Java ソースファイルのドキュメンテーションコメントの影響を受けない独立した HTML ファイルなどがあります。 360 .LP 361 処理されないファイルを含めるには、\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 はパッケージではないからです。つまり、java に直接含まれているソースファイルは 1 つも存在していません。 362 .LP 363 これらの未処理のファイルへのリンクは、すべて明示的に記述する必要があります。これは、Javadoc ツールがそれらのファイルを見ずに、単にディレクトリとその内容を生成先にコピーするだけだからです。たとえば、 \f2Button.java\fP のドキュメンテーションコメント内のリンクは、次のようになります。 364 .nf 365 \f3 366 .fl 367 /** 368 .fl 369 * This button looks like this: 370 .fl 371 * <img src="doc\-files/Button.gif"> 372 .fl 373 */ 374 .fl 375 \fP 376 .fi 377 .SS 378 テストファイルおよびテンプレートファイル 379 .LP 380 一部の開発者から、テストファイルおよびテンプレートファイルを対応するソースファイルの近くのソースツリーに保存したいという要望がありました。つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに保存したいということです。 381 .LP 382 個別のソースファイル名で明示的に渡して Javadoc ツールを実行する場合は、テストファイルおよびテンプレートファイルを意図的に除外して、処理されないようにすることができます。ただし、パッケージ名またはワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイルおよびテンプレートファイルが処理されないようにする必要があります。 383 .LP 384 テストファイルとテンプレートファイルの違いは、テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、テンプレートファイルは、そうではないという点です。ただし、テンプレートファイルも「.java」で終わることができます。 385 .LP 386 \f3テストファイル\fP \- 開発者の多くは、あるパッケージのコンパイル可能で実行可能なテストファイルをそのパッケージのソースファイルと同じディレクトリに配置したいと考えています。しかしテストファイルは、名前なしパッケージなど、ソースファイルパッケージとは別のパッケージに属させたいとも考えています (そのため、テストファイルには package ステートメントがないか、またはソースとは別の package ステートメントがある)。このような状況では、コマンド行で指定されているソースのパッケージ名を指定してそのソースがドキュメント化されているときに、テストファイルは警告またはエラーを引き起こします。そのようなテストファイルはサブディレクトリに配置する必要があります。たとえば、 \f2com.package1\fP 内のソースファイルに対するテストファイルを追加する場合は次のように、ハイフンを含んでいるためにパッケージ名としては無効であるようなサブディレクトリ内に、それらのファイルを配置します。 387 .nf 388 \f3 389 .fl 390 com/package1/test\-files/ 391 .fl 392 \fP 393 .fi 394 .LP 395 こうすると、Javadoc ツールでは警告なしで test ディレクトリをスキップします。 396 .LP 397 テストファイルに doc コメントが含まれる場合、次のようにワイルドカードを含んだテストソースファイル名で渡してテストファイルのドキュメントを生成するように、Javadoc ツールを別個に実行できるように設定できます。たとえば、 \f2com/package1/test\-files/*.java などです\fP。 398 .LP 399 \f3ソースファイルのテンプレート\fP \- テンプレートファイルの名前は「.java」で終わることもありますが、テンプレートファイルはコンパイルできません。ソースディレクトリ内に保持したいソースファイルのテンプレートがある場合は、 \f2Buffer\-Template.java\fP のようにハイフンやその他の無効な Java 文字を名前に含めることで、テンプレートが処理されないようにします。これは、Javadoc ツールが処理するのは、「.java」接尾辞を除いた名前が 正規のクラス名であるソースファイルだけであるためです (Java 言語仕様の「Identifiers」に関する情報を参照)。 400 .SH "生成されるファイル" 401 .LP 402 デフォルトでは、javadoc ツールは、HTML 形式のドキュメントを生成する標準ドックレットを使います。このドックレットは、以下の種類のファイルを生成します。それぞれの HTML ページは、個々のファイルに相当します。javadoc が生成するファイルの名前には、クラスやインタフェースの名前にちなんだものと、そうでないもの ( \f2package\-summary.html など\fP) の 2 種類があります。後者のグループのファイル名には、前者のグループとファイル名が競合しないように、ハイフンが含まれています。 403 .LP 404 \f3基本内容ページ\fP 405 .RS 3 406 .TP 2 407 o 408 ドキュメント化するクラスまたはインタフェースごとに 1 つの\f3クラスページまたはインタフェースページ\fP (\f2クラス名\fP\f2.html\fP) 409 .TP 2 410 o 411 ドキュメント化するパッケージごとに 1 つの\f3パッケージページ\fP (\f2package\-summary.html\fP)。Javadoc ツールは、 \f2package.html\fP または \f2package\-info.java\fP という名前のファイル内の HTML テキストをすべて組み入れます。 412 .TP 2 413 o 414 パッケージのセット全体に対して 1 つの\f3概要ページ\fP (\f2overview\-summary.html\fP)。これは、生成ドキュメントの先頭ページになります。Javadoc ツールは、\f2\-overview\fP オプションで指定されたファイル内の HTML テキストをすべて組み入れます。このページのファイルは、javadoc に複数のパッケージ名を渡した場合にだけ作成されます。詳細は、「HTML フレーム」を参照してください。 415 .RE 416 .LP 417 \f3相互参照ページ\fP 418 .RS 3 419 .TP 2 420 o 421 \f3パッケージのセット全体に対して 1 つのクラス階層ページ\fP (\f2overview\-tree.html\fP)。このページを表示するには、ナビゲーションバーの [概要] をクリックしてから、[階層ツリー] をクリックします。 422 .TP 2 423 o 424 \f3パッケージごとに 1 つのクラス階層ページ\fP (\f2package\-tree.html\fP)。これを表示するには、特定のパッケージ、クラス、またはインタフェースのページに移動し、[階層ツリー] をクリックしてそのパッケージの階層を表示させます。 425 .TP 2 426 o 427 \f3パッケージごとに 1 つの [使用] ページ\fP (\f2package\-use.html\fP) と、クラスおよびインタフェースごとに 1 つずつの [使用] ページ (\f2class\-use/\fP\f2クラス名\fP\f2.html\fP)。このページには、特定のクラス、インタフェース、またはパッケージの一部を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。クラスまたはインタフェース A を例にして考えると、その [使用] ページには、A のサブクラス、A として宣言されたフィールド、A を返すメソッド、A 型のパラメータを持つメソッドおよびコンストラクタが表示されます。 このページを表示するには、まず、パッケージ、クラス、またはインタフェースのページに移動してから、ナビゲーションバーの [使用] リンクをクリックします。 428 .TP 2 429 o 430 \f3非推奨 API ページ\fP (\f2deprecated\-list.html\fP)。推奨されない名前がすべて一覧表示されます。非推奨名は、一般に改良された API が存在するために使用が推奨されていない API の名前であり、通常、それに置き換わる名前が提示されています。非推奨 API は、将来の実装では削除される可能性があります。 431 .TP 2 432 o 433 \f3定数フィールド値ページ\fP (\f2constant\-values.html\fP)。static フィールドの値用です。 434 .TP 2 435 o 436 \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 クラスの完全に直列化されたクラスを生成できます。 437 .TP 2 438 o 439 \f3索引\fP (\f2index\-*.html\fP)。すべてのクラス、インタフェース、コンストラクタ、フィールド、およびメソッドの名前がアルファベット順に並んでいます。索引は、Unicode を扱えるように国際化されています。1 つのファイルとして生成することも、先頭文字 (英語の場合 A ~ Z) ごとに別々のファイルとして生成することもできます。 440 .RE 441 .LP 442 \f3サポートファイル\fP 443 .RS 3 444 .TP 2 445 o 446 \f3ヘルプページ\fP (\f2help\-doc.html\fP)。ナビゲーションバーや前述の各ページに関する説明が記載されています。デフォルトのヘルプファイルに代わる独自のカスタムヘルプファイルを提供するには、\f2\-helpfile\fP を使用します。 447 .TP 2 448 o 449 表示用の HTML フレームを作成する 1 つの \f3index.html ファイル\fP。このファイルは、フレーム付きの先頭ページを表示する場合にロードします。このファイル自体には、テキスト内容は含まれていません。 450 .TP 2 451 o 452 複数の\f3フレームファイル\fP (\f2*\-frame.html\fP)。パッケージ、クラス、およびインタフェースのリストが含まれています。HTML フレームを表示するときに使用されます。 453 .TP 2 454 o 455 \f3パッケージリスト\fPファイル (\f2package\-list\fP)。 \f2\-link\fP および \f2\-linkoffline\fP オプションで使用されます。これは、HTML ファイルではなくテキストファイルであり、どのリンクからもアクセスできません。 456 .TP 2 457 o 458 \f3スタイルシート\fPファイル (\f2stylesheet.css\fP)。生成されるページ上のいくつかの要素について、色、フォントファミリ、フォントサイズ、フォントのスタイル、および配置を制御します。 459 .TP 2 460 o 461 \f3doc\-files\fP ディレクトリ。生成先ディレクトリにコピーするイメージ、サンプルコード、ソースコードなどのファイルがすべて格納されます。これらのファイルは、Javadoc ツールによって処理されないため、ファイル内に ｊavadoc タグがあっても無視されます。このディレクトリは、ソースツリーの中にある場合にのみ生成されます。 462 .RE 463 .LP 464 \f3HTML フレーム\fP 465 .LP 466 Javadoc ツールは、下の図に示すように、2 ~ 3 つの HTML フレームを生成します。1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。単一のパッケージに属するソースファイル (*.java) または単一のパッケージ名を引数として javadoc コマンドに渡す場合は、左側の列にクラスの一覧を表示するフレーム (C) 1 つだけが作成されます。Javadoc に複数のパッケージ名を渡した場合は、概要ページ (Detail) に加えて、すべてのパッケージを一覧表示する第 3 のフレーム (P) が作成されます。この概要ページのファイル名は、 \f2overview\-summary.html です\fP。したがって、このファイルは、2 つ以上のパッケージ名を渡した場合にだけ作成されます。「フレームなし」リンクをクリックするか、overview\-summary.html を最初に表示すると、フレームを省略できます。 467 .LP 468 HTML フレームに慣れていない場合は、特定のフレームを印刷およびスクロールするには、そのフレームに「フォーカス」がなければならないことに注意してください。フレームにフォーカスを与えるには、そのフレームをクリックします。このようにすると、多くのブラウザでは、矢印キーやページキーを使ってそのフレームをスクロールしたり、「印刷」メニューコマンドを使ってそのフレームを印刷したりできます。 469 .LP 470 HTML フレームが必要かどうかによって、次のどちらかのファイルを開始ページとしてロードします。 471 .RS 3 472 .TP 2 473 o 474 \f2index.html\fP (フレームあり) 475 .TP 2 476 o 477 \f2overview\-summary.html\fP (フレームなし) 478 .RE 479 .LP 480 \f3生成されるファイルの構造\fP 481 .LP 482 生成されるクラスファイルおよびインタフェースファイルは、Java ソースファイルおよびクラスファイルと同じディレクトリ階層に編成されます。1 つのサブパッケージにつき 1 つのディレクトリ、という構造になります。 483 .LP 484 たとえば、 \f2java.applet.Applet\fP クラス用に生成されたドキュメントは、 \f2java/applet/Applet.html\fP に格納されます。生成先のディレクトリの名前が \f2apidocs\fP だとすると、java.applet パッケージのファイル構造は、その下に構築されます。前述のように、「frame」という語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外の HTML ファイルは、すべて右側のフレームに表示されます。 485 .LP 486 注 \- 下の階層図で、ディレクトリは\f3太字\fP (bold) で示してあります。アスタリスク (\f2*\fP) は、javadoc への引数がパッケージ名ではなくソースファイル名 (*.java) である場合に省略されるファイルおよびディレクトリを示しています。また、引数がソースファイル名の場合、 \f2package\-list\fP は作成されますが、その中身は空です。doc\-files ディレクトリは、ソースツリー内に存在する場合にのみ、生成先に作成されます。 487 .nf 488 \f3 489 .fl 490 491 .fl 492 \fP\f3apidocs\fP 最上位ディレクトリ 493 .fl 494 index.html HTML フレームを設定する初期ページ 495 .fl 496 * overview\-summary.html 全パッケージのリスト。先頭文による要約付き 497 .fl 498 overview\-tree.html 全パッケージのクラス階層のリスト 499 .fl 500 deprecated\-list.html 全パッケージの非推奨 API のリスト 501 .fl 502 constant\-values.html 全パッケージの static フィールドの値のリスト 503 .fl 504 serialized\-form.html 全パッケージの直列化された形式のリスト 505 .fl 506 * overview\-frame.html 全パッケージのリスト。左上のフレームで使用される 507 .fl 508 allclasses\-frame.html 全パッケージの全クラスのリスト。左下のフレームで使用される 509 .fl 510 help\-doc.html これらのページの構成を示すユーザーヘルプのリスト 511 .fl 512 index\-all.html \-splitindex オプションを指定しなかった場合に作成されるデフォルトの索引 513 .fl 514 \f3index\-files\fP \-splitindex オプションを指定した場合に作成されるディレクトリ 515 .fl 516 index\-<number>.html \-splitindex オプションを指定した場合に作成される索引ファイル 517 .fl 518 package\-list パッケージ名のリスト。外部参照を解決するためだけに使用される 519 .fl 520 stylesheet.css フォント、色、配置を定義する HTML スタイルシート 521 .fl 522 \f3java\fP パッケージディレクトリ 523 .fl 524 \f3applet\fP サブパッケージディレクトリ 525 .fl 526 Applet.html Applet クラスのページ 527 .fl 528 AppletContext.html AppletContext インタフェースのページ 529 .fl 530 AppletStub.html AppletStub インタフェースのページ 531 .fl 532 AudioClip.html AudioClip インタフェースのページ 533 .fl 534 * package\-summary.html このパッケージのクラスのリスト。先頭文による要約付き 535 .fl 536 * package\-frame.html このパッケージのクラスのリスト。左下のフレームで使用される 537 .fl 538 * package\-tree.html このパッケージのクラス階層のリスト 539 .fl 540 package\-use このパッケージが使用されている場所のリスト 541 .fl 542 \f3doc\-files\fP 画像やサンプルファイルを保持するディレクトリ 543 .fl 544 \f3class\-use\fP API が使用されている場所のページを保持するディレクトリ 545 .fl 546 Applet.html Applet クラスの使用に関するページ 547 .fl 548 AppletContext.html AppletContext インタフェースの使用に関するページ 549 .fl 550 AppletStub.html AppletStub インタフェースの使用に関するページ 551 .fl 552 AudioClip.html AudioClip インタフェースの使用に関するページ 553 .fl 554 \f3src\-html\fP ソースコードディレクトリ 555 .fl 556 \f3java\fP パッケージディレクトリ 557 .fl 558 \f3applet\fP サブパッケージディレクトリ 559 .fl 560 Applet.html Applet ソースコードのページ 561 .fl 562 AppletContext.html AppletContext ソースコードのページ 563 .fl 564 AppletStub.html AppletStub ソースコードのページ 565 .fl 566 AudioClip.html AudioClip ソースコードのページ 567 .fl 568 .fi 569 .SS 570 生成される API 宣言 571 .LP 572 Javadoc ツールは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの説明の最初に、その API 用の宣言を生成します。たとえば、 \f2Boolean\fP クラスの宣言は、次のようになります。 573 .LP 574 \f2public final class Boolean\fP 575 .br 576 \f2extends Object\fP 577 .br 578 \f2implements Serializable\fP 579 .LP 580 また、 \f2Boolean.valueOf\fP メソッドの宣言は、次のようになります。 581 .LP 582 \f2public static Boolean valueOf(String s)\fP 583 .LP 584 Javadoc ツールでは、修飾子 \f2public\fP、 \f2protected\fP、 \f2private\fP、 \f2abstract\fP、 \f2final\fP、 \f2static\fP、 \f2transient\fP、および \f2volatile\fP は組み込めますが、 \f2synchronized\fP と \f2native\fP は組み込めません。これら後者の 2 つの修飾子は、実装の詳細と見なされているため、API 仕様には含まれません。 585 .LP 586 API では、並行性セマンティクスについて、キーワード \f2synchronized\fP に依存するのではなく、コメントの主説明としてドキュメント化すべきです。 \f2たとえば、「1 つの Enumeration を\fP 複数のスレッドから並行して使用することはできない」などと記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述するべきではありません。たとえば、 \f2Hashtable\fP はスレッドに対して安全である必要がありますが、「エクスポートされるすべてのメソッドを同期化すればそれを実現できる」のようには指定する根拠はありません。バケットレベルで内部的に同期化する権利を残しておく必要があります。そうすれば、より高度な並行性が提供されます。 587 .SH "ドキュメンテーションコメント" 588 .LP 589 オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。 590 .SS 591 ソースコードへのコメントの挿入 592 .LP 593 ソースコードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーションコメント ("doc comments") を記述することができます。各パッケージにドキュメンテーションコメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーションコメントを作成できます。ドキュメンテーションコメントは、非公式に「Javadoc コメント」と呼ばれています (この用語は商標関連の使用法に違反)。ドキュメンテーションコメントは、コメントを始まりを示す文字列 \f2/**\fP と、コメントを終わりを示す文字列 \f2*/\fP の間にある文字から構成されます。行の先頭のアスタリスクは、各行に記述できます。詳細は、以下で説明します。コメントのテキストは、複数行にわたって記述できます。 594 .nf 595 \f3 596 .fl 597 /** 598 .fl 599 * This is the typical format of a simple documentation comment 600 .fl 601 * that spans two lines. 602 .fl 603 */ 604 .fl 605 \fP 606 .fi 607 .LP 608 次のようにして 1 行に記述すると、スペースを節約できます。 609 .nf 610 \f3 611 .fl 612 /** This comment takes up only one line.*/ 613 .fl 614 \fP 615 .fi 616 .LP 617 \f3コメントの配置\fP \- ドキュメンテーションコメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置かれているときにだけ認識されます。クラスの例、メソッドの例、およびフィールドの例を参照してください。メソッドの本体に置かれているドキュメンテーションコメントは無視されます。javadoc ツールでは、1 つの宣言文につき 1 つのドキュメンテーションコメントだけが認識されます。 618 .LP 619 よくある間違いは、クラスコメントとクラス宣言の間に \f2import\fP 文を置いてしまうことです。このような記述はしないでください。このようなクラスコメントは無視されます。 620 .nf 621 \f3 622 .fl 623 /** 624 .fl 625 * This is the class comment for the class Whatever. 626 .fl 627 */ 628 .fl 629 630 .fl 631 import com.sun; // MISTAKE \- Important not to put import statement here 632 .fl 633 634 .fl 635 public class Whatever { 636 .fl 637 } 638 .fl 639 \fP 640 .fi 641 .LP 642 \f3ドキュメンテーションコメントは主説明のあとにタグセクションが続く \- コメントの開始区切り文字である\fP \f2/**\fP のあとからタグセクションまでが主説明になります。タグセクションは、行の先頭にある最初の \f2@\fP で定義される最初のブロックタグから始まります (先頭のアスタリスク、空白、先頭の区切り文字 \f2/**\fP は除く)。主説明を記述せず、タグセクションだけのコメントを記述することもできます。主説明は、タグセクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。何回も記述できるタグと、1 回しか記述できないタグがあります。たとえば、次の \f2@see\fP は、タグセクションを開始しています。 643 .nf 644 \f3 645 .fl 646 /** 647 .fl 648 * This sentence would hold the main description for this doc comment. 649 .fl 650 * @see java.lang.Object 651 .fl 652 */ 653 .fl 654 \fP 655 .fi 656 .LP 657 \f3ブロックタグとインラインタグ\fP \- \f2「タグ」\fPは、Javadoc が処理できる、ドキュメンテーションコメント内の特別なキーワードです。タグには 2 種類あります。1 つは @tag のように表記されるブロックタグ \f2(「標準タグ」とも呼ばれる)、\fP もう 1 つは {@tag} のように中括弧で囲まれるインラインタグ \f2です\fP。ブロックタグが正しく解釈されるためには、行の先頭のアスタリスク、空白、区切り文字 (\f2/**\fP) を除いて、行の先頭に置かなければなりません。これは、 \f2@\fP 文字をテキスト内の別の場所で使用した場合にはタグの開始として解釈されないことを意味しています。行の先頭で \f2@\fP 文字を使用してもそれが解釈されないようにするには、HTML エンティティー \f2@\fP を使用します。それぞれのブロックタグには、対応付けられたテキストがあります。このテキストは、タグのあとから、次のタグの前、またはドキュメンテーションコメントの最後までの間に記述されたテキスト (タグやコメント区切り文字を除く) です。この関連テキストは複数行にわたって記述できます。インラインタグは、テキストを記述できる場所であればどこにでも置くことができ、正しく解釈されます。次の例にはブロックタグ \f2@deprecated\fP とインラインタグ \f2{@link}\fP が含まれています。 658 .nf 659 \f3 660 .fl 661 /** 662 .fl 663 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} 664 .fl 665 */ 666 .fl 667 \fP 668 .fi 669 .LP 670 \f3コメントは HTML で記述する\fP \- テキストは HTML 形式で記述しなければなりません。これは、HTML のエンティティーを使う必要があること、および HTML タグを使用できることを意味します。記述する HTML のバージョンとしては、使用するブラウザがサポートする任意のバージョンを使用できます。標準ドックレットは、カスケーディングスタイルシート (CSS) とフレームを含め、すべての部分 (ドキュメンテーションコメント以外の部分) で HTML 3.2 に準拠したコードを生成するように作成されています。ただし、フレームセット対応のため、生成される各ファイルには「HTML 4.0」と記述されます。 671 .LP 672 たとえば、より小さい (\f2<\fP) 記号およびより大きい (\f2>\fP) 記号のエンティティーは、 \f2<\fP および \f2>\fP と記述すべきです。同様に、アンパサンド (\f2&\fP) は \f2&\fP と記述すべきです。次の例ではボールドの HTML タグ \f2<b>\fP が示されています。 673 .LP 674 次に、ドキュメンテーションコメントを示します。 675 .nf 676 \f3 677 .fl 678 /** 679 .fl 680 * This is a <b>doc</b> comment. 681 .fl 682 * @see java.lang.Object 683 .fl 684 */ 685 .fl 686 \fP 687 .fi 688 .LP 689 \f3行頭のアスタリスク\fP \- javadoc によるドキュメンテーションコメントの解析時に、各行の先頭にあるアスタリスク (\f2*\fP) 文字は破棄されます。最初のアスタリスク (\f2*\fP) 文字より前にある空白やタブも破棄されます。バージョン 1.4 からは、行の先頭のアスタリスクを省略しても、先頭の空白文字は削除されなくなりました。このため、コード例を直接ドキュメンテーションコメントの \f2<PRE>\fP タグ内にペーストしても、インデントが保持されます。通常、ブラウザは、空白文字をタブよりも一律に解釈します。インデントの起点は左マージンになります (区切り文字 \f2/**\fP または \f2<PRE>\fP タグではなく)。 690 .LP 691 \f3最初の文\fP \- 各ドキュメンテーションコメントの最初の文は、宣言されているエンティティーに関する簡潔かつ完全な要約文である必要があります。この「最初の文」は、直後にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のタグがある位置で終わります。最初の文は、Javadoc ツールによって HTML ページの最初にあるメンバーの概要の部分にコピーされます。 692 .LP 693 \f3複数フィールドの宣言\fP \- Java では、1 つの文で複数のフィールドを宣言できます。ただし、この文には、1 つのドキュメンテーションコメントしか記述できません。そのコメントが、すべてのフィールドに対してコピーされます。したがって、フィールドごとにドキュメンテーションコメントを記述する必要がある場合は、各フィールドを別々の文で宣言しなければなりません。たとえば、次のドキュメンテーションコメントは、1 つの宣言として記述すると不適切です。この場合は、宣言を 2 つに分けることをお勧めします。 694 .nf 695 \f3 696 .fl 697 /** 698 .fl 699 * The horizontal and vertical distances of point (x,y) 700 .fl 701 */ 702 .fl 703 public int x, y; // Avoid this 704 .fl 705 \fP 706 .fi 707 .LP 708 上記のコードからは、次のようなドキュメントが生成されます。 709 .nf 710 \f3 711 .fl 712 public int \fP\f3x\fP 713 .fl 714 .fi 715 .RS 3 716 The horizontal and vertical distances of point (x,y) 717 .RE 718 .nf 719 \f3 720 .fl 721 public int \fP\f3y\fP 722 .fl 723 .fi 724 .RS 3 725 The horizontal and vertical distances of point (x,y) 726 .RE 727 .LP 728 \f3見出しタグはなるべく使用しない\fP \- メンバーに対してドキュメンテーションコメントを記述するときには、<H1> や <H2> などの HTML 見出しタグは、なるべく使わないでください。 Javadoc ツールは、完全に構造化されたドキュメントを作成するので、このような構造化タグが使われていると、生成ドキュメントの形式が悪影響を受けることがあります。ただし、クラスやパッケージのコメントでは、これらの見出しタグを使って独自の構造を組み立ててかまいません。 729 .SS 730 メソッドコメントの自動コピー 731 .LP 732 Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。 733 .RS 3 734 .TP 2 735 o 736 \f3自動的にコメントを継承して見つからないテキストを埋める\fP \- 主説明、 \f2@return\fP タグ、 \f2@param\fP タグ、または \f2@throws\fP タグがメソッドコメントに見つからない場合、Javadoc ツールは、オーバーライドまたは実装している場合はその対象となるメソッドから、対応する主説明またはタグコメントを、次のアルゴリズムに従ってコピーします。 737 .LP 738 厳密には、特定のパラメータの \f2@param\fP タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の \f2@throws\fP タグが見つからない場合、その例外が宣言されている場合にかぎり、 \f2@throws\fP タグがコピーされます。 739 .LP 740 この動作はバージョン 1.3 以前の動作とは対照的です。これまでのバージョンでは、主説明またはタグが存在すれば、コメントは一切継承されませんでした。 741 .TP 2 742 o 743 \f3{@inheritDoc} タグを含むコメントを明示的に継承する\fP \- インラインタグ \f2{@inheritDoc}\fP を、メソッドの主説明内または \f2@return\fP タグ、 \f2@param\fP タグ、または \f2@throws\fP のいずれかのタグコメント内に挿入します。対応する継承された主説明またはタグコメントがその位置にコピーされます。 744 .RE 745 .LP 746 ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが \-sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスがドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。 747 .LP 748 \f3クラスおよびインタフェースからの継承\fP \- クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。 749 .RS 3 750 .TP 2 751 o 752 クラスのメソッドがスーパークラスのメソッドをオーバーライドしている 753 .TP 2 754 o 755 インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている 756 .TP 2 757 o 758 クラスのメソッドがインタフェースのメソッドを実装している 759 .RE 760 .LP 761 最初の 2 つのケース (メソッドがオーバーライドしている場合) では、Javadoc ツールは、そのコメントが継承されているかどうかにかかわらず、オーバーライドしているメソッドのドキュメント内に「オーバーライド」という小見出しを生成し、オーバーライドされているメソッドへのリンクを書き込みます。 762 .LP 763 3 つ目のケース (特定のクラスのメソッドがインタフェースのメソッドを実装している場合) では、javadoc ツールは、オーバーライドしているメソッドのドキュメント内に「定義」という小見出しを生成し、実装されているメソッドへのリンクを書き込みます。これは、コメントが継承されているかどうかにかかわりません。 764 .LP 765 \f3メソッドの説明が継承されるアルゴリズム\fP \- あるメソッドにドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、Javadoc ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。 このアルゴリズムは、もっとも適切なドキュメンテーションコメントを検索できるように設計されており、スーパークラスよりもインタフェースが優先されるようになっています。 766 .RS 3 767 .TP 3 768 1. 769 直接に実装されている (または、拡張されている) インタフェースを、メソッドの宣言で implements (または extends) キーワードのあとに登場する順序で、1 つずつ調べる。このメソッドについて最初に見つかったドキュメンテーションコメントを採用する 770 .TP 3 771 2. 772 手順 1 でドキュメンテーションコメントが見つからなかった場合は、直接実装されている (または、拡張されている) インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ) 773 .TP 3 774 3. 775 手順 2 でドキュメンテーションコメントが見つからなかった場合で、このクラスが Object 以外のクラスである (インタフェースではない) 場合は、次のように処理する 776 .RS 3 777 .TP 3 778 a. 779 スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する 780 .TP 3 781 b. 782 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する 783 .RE 784 .RE 785 .SH "javadoc タグ" 786 .LP 787 Javadoc ツールは、Java のドキュメンテーションコメント内に埋め込まれた特別なタグを解析します。これらのドキュメンテーションタグを使うと、書式の整った完全な API ドキュメントをソースコードから自動的に生成できます。タグは「アットマーク」記号 (\f2@\fP) で始まり、大文字と小文字の区別があります。タグは、大文字と小文字を使用して、表示されているとおりに入力する必要があります。タグは、行の先頭 (先行する空白と省略可能なアスタリスクは除く) に置かなければなりません。慣例として、同じ名前のタグは 1 か所にまとめて記述するようにします。たとえば、 \f2@see\fP タグはすべて同じ場所に配置します。 788 .LP 789 タグには 2 つのタイプがあります。 790 .RS 3 791 .TP 2 792 o 793 \f3ブロックタグ\fP \- 主説明に続くタグセクション内にのみ記述可能。ブロックタグは、 \f2@tag\fP の形式をとります。 794 .TP 2 795 o 796 \f3インラインタグ\fP \- 主説明内、またはブロックタグのコメント内に記述可能。インラインタグは、 \f2{@tag}\fP.のように中括弧で囲みます。 797 .RE 798 .LP 799 今後のリリースで導入されるタグについては、 800 .na 801 \f2「Proposed Javadoc Tags」\fP @ 802 .fi 803 http://java.sun.com/j2se/javadoc/proposed\-tags.htmlを参照してください。 804 .LP 805 現時点で有効なタグは、次のとおりです。 806 .LP 807 .TS 808 .if \n+(b.=1 .nr d. \n(.c-\n(c.-1 809 .de 35 810 .ps \n(.s 811 .vs \n(.vu 812 .in \n(.iu 813 .if \n(.u .fi 814 .if \n(.j .ad 815 .if \n(.j=0 .na 816 .. 817 .nf 818 .nr #~ 0 819 .if n .nr #~ 0.6n 820 .ds #d .d 821 .if \(ts\n(.z\(ts\(ts .ds #d nl 822 .fc 823 .nr 33 \n(.s 824 .rm 80 81 825 .nr 34 \n(.lu 826 .eo 827 .am 81 828 .br 829 .di a+ 830 .35 831 .ft \n(.f 832 .ll \n(34u*1u/3u 833 .if \n(.l<\n(81 .ll \n(81u 834 .in 0 835 \f3導入された JDK/SDK のバージョン\fP 836 .br 837 .di 838 .nr a| \n(dn 839 .nr a- \n(dl 840 .. 841 .ec \ 842 .35 843 .nf 844 .ll \n(34u 845 .nr 80 0 846 .nr 38 \w\f3タグ\fP 847 .if \n(80<\n(38 .nr 80 \n(38 848 .nr 38 \w\f2@author\fP 849 .if \n(80<\n(38 .nr 80 \n(38 850 .nr 38 \w\f2{@code}\fP 851 .if \n(80<\n(38 .nr 80 \n(38 852 .nr 38 \w\f2{@docRoot}\fP 853 .if \n(80<\n(38 .nr 80 \n(38 854 .nr 38 \w\f2@deprecated\fP 855 .if \n(80<\n(38 .nr 80 \n(38 856 .nr 38 \w\f2@exception\fP 857 .if \n(80<\n(38 .nr 80 \n(38 858 .nr 38 \w\f2{@inheritDoc}\fP 859 .if \n(80<\n(38 .nr 80 \n(38 860 .nr 38 \w\f2{@link}\fP 861 .if \n(80<\n(38 .nr 80 \n(38 862 .nr 38 \w\f2{@linkplain}\fP 863 .if \n(80<\n(38 .nr 80 \n(38 864 .nr 38 \w\f2{@literal}\fP 865 .if \n(80<\n(38 .nr 80 \n(38 866 .nr 38 \w\f2@param\fP 867 .if \n(80<\n(38 .nr 80 \n(38 868 .nr 38 \w\f2@return\fP 869 .if \n(80<\n(38 .nr 80 \n(38 870 .nr 38 \w\f2@see\fP 871 .if \n(80<\n(38 .nr 80 \n(38 872 .nr 38 \w\f2@serial\fP 873 .if \n(80<\n(38 .nr 80 \n(38 874 .nr 38 \w\f2@serialData\fP 875 .if \n(80<\n(38 .nr 80 \n(38 876 .nr 38 \w\f2@serialField\fP 877 .if \n(80<\n(38 .nr 80 \n(38 878 .nr 38 \w\f2@since\fP 879 .if \n(80<\n(38 .nr 80 \n(38 880 .nr 38 \w\f2@throws\fP 881 .if \n(80<\n(38 .nr 80 \n(38 882 .nr 38 \w\f2{@value}\fP 883 .if \n(80<\n(38 .nr 80 \n(38 884 .nr 38 \w\f2@version\fP 885 .if \n(80<\n(38 .nr 80 \n(38 886 .80 887 .rm 80 888 .nr 81 0 889 .nr 38 \w1.0 890 .if \n(81<\n(38 .nr 81 \n(38 891 .nr 38 \w1.5 892 .if \n(81<\n(38 .nr 81 \n(38 893 .nr 38 \w1.3 894 .if \n(81<\n(38 .nr 81 \n(38 895 .nr 38 \w1.0 896 .if \n(81<\n(38 .nr 81 \n(38 897 .nr 38 \w1.0 898 .if \n(81<\n(38 .nr 81 \n(38 899 .nr 38 \w1.4 900 .if \n(81<\n(38 .nr 81 \n(38 901 .nr 38 \w1.2 902 .if \n(81<\n(38 .nr 81 \n(38 903 .nr 38 \w1.4 904 .if \n(81<\n(38 .nr 81 \n(38 905 .nr 38 \w1.5 906 .if \n(81<\n(38 .nr 81 \n(38 907 .nr 38 \w1.0 908 .if \n(81<\n(38 .nr 81 \n(38 909 .nr 38 \w1.0 910 .if \n(81<\n(38 .nr 81 \n(38 911 .nr 38 \w1.0 912 .if \n(81<\n(38 .nr 81 \n(38 913 .nr 38 \w1.2 914 .if \n(81<\n(38 .nr 81 \n(38 915 .nr 38 \w1.2 916 .if \n(81<\n(38 .nr 81 \n(38 917 .nr 38 \w1.2 918 .if \n(81<\n(38 .nr 81 \n(38 919 .nr 38 \w1.1 920 .if \n(81<\n(38 .nr 81 \n(38 921 .nr 38 \w1.2 922 .if \n(81<\n(38 .nr 81 \n(38 923 .nr 38 \w1.4 924 .if \n(81<\n(38 .nr 81 \n(38 925 .nr 38 \w1.0 926 .if \n(81<\n(38 .nr 81 \n(38 927 .81 928 .rm 81 929 .nr 38 \n(a- 930 .if \n(81<\n(38 .nr 81 \n(38 931 .35 932 .nf 933 .ll \n(34u 934 .nr 38 1n 935 .nr 79 0 936 .nr 40 \n(79+(0*\n(38) 937 .nr 80 +\n(40 938 .nr 41 \n(80+(3*\n(38) 939 .nr 81 +\n(41 940 .nr TW \n(81 941 .if t .if \n(TW>\n(.li .tm Table at line 851 file Input is too wide - \n(TW units 942 .fc 943 .nr #T 0-1 944 .nr #a 0-1 945 .eo 946 .de T# 947 .ds #d .d 948 .if \(ts\n(.z\(ts\(ts .ds #d nl 949 .mk ## 950 .nr ## -1v 951 .ls 1 952 .ls 953 .. 954 .ec 955 .ne \n(a|u+\n(.Vu 956 .if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v) 957 .ta \n(80u \n(81u 958 .nr 31 \n(.f 959 .nr 35 1m 960 \&\h'|\n(40u'\f3タグ\fP\h'|\n(41u' 961 .mk ## 962 .nr 31 \n(## 963 .sp |\n(##u-1v 964 .nr 37 (\n(41u+\n(81u-\n(a-u)/2u 965 .in +\n(37u 966 .a+ 967 .in -\n(37u 968 .mk 32 969 .if \n(32>\n(31 .nr 31 \n(32 970 .sp |\n(31u 971 .ta \n(80u \n(81u 972 .nr 31 \n(.f 973 .nr 35 1m 974 \&\h'|\n(40u'\f2@author\fP\h'|\n(41u'1.0 975 .ta \n(80u \n(81u 976 .nr 31 \n(.f 977 .nr 35 1m 978 \&\h'|\n(40u'\f2{@code}\fP\h'|\n(41u'1.5 979 .ta \n(80u \n(81u 980 .nr 31 \n(.f 981 .nr 35 1m 982 \&\h'|\n(40u'\f2{@docRoot}\fP\h'|\n(41u'1.3 983 .ta \n(80u \n(81u 984 .nr 31 \n(.f 985 .nr 35 1m 986 \&\h'|\n(40u'\f2@deprecated\fP\h'|\n(41u'1.0 987 .ta \n(80u \n(81u 988 .nr 31 \n(.f 989 .nr 35 1m 990 \&\h'|\n(40u'\f2@exception\fP\h'|\n(41u'1.0 991 .ta \n(80u \n(81u 992 .nr 31 \n(.f 993 .nr 35 1m 994 \&\h'|\n(40u'\f2{@inheritDoc}\fP\h'|\n(41u'1.4 995 .ta \n(80u \n(81u 996 .nr 31 \n(.f 997 .nr 35 1m 998 \&\h'|\n(40u'\f2{@link}\fP\h'|\n(41u'1.2 999 .ta \n(80u \n(81u 1000 .nr 31 \n(.f 1001 .nr 35 1m 1002 \&\h'|\n(40u'\f2{@linkplain}\fP\h'|\n(41u'1.4 1003 .ta \n(80u \n(81u 1004 .nr 31 \n(.f 1005 .nr 35 1m 1006 \&\h'|\n(40u'\f2{@literal}\fP\h'|\n(41u'1.5 1007 .ta \n(80u \n(81u 1008 .nr 31 \n(.f 1009 .nr 35 1m 1010 \&\h'|\n(40u'\f2@param\fP\h'|\n(41u'1.0 1011 .ta \n(80u \n(81u 1012 .nr 31 \n(.f 1013 .nr 35 1m 1014 \&\h'|\n(40u'\f2@return\fP\h'|\n(41u'1.0 1015 .ta \n(80u \n(81u 1016 .nr 31 \n(.f 1017 .nr 35 1m 1018 \&\h'|\n(40u'\f2@see\fP\h'|\n(41u'1.0 1019 .ta \n(80u \n(81u 1020 .nr 31 \n(.f 1021 .nr 35 1m 1022 \&\h'|\n(40u'\f2@serial\fP\h'|\n(41u'1.2 1023 .ta \n(80u \n(81u 1024 .nr 31 \n(.f 1025 .nr 35 1m 1026 \&\h'|\n(40u'\f2@serialData\fP\h'|\n(41u'1.2 1027 .ta \n(80u \n(81u 1028 .nr 31 \n(.f 1029 .nr 35 1m 1030 \&\h'|\n(40u'\f2@serialField\fP\h'|\n(41u'1.2 1031 .ta \n(80u \n(81u 1032 .nr 31 \n(.f 1033 .nr 35 1m 1034 \&\h'|\n(40u'\f2@since\fP\h'|\n(41u'1.1 1035 .ta \n(80u \n(81u 1036 .nr 31 \n(.f 1037 .nr 35 1m 1038 \&\h'|\n(40u'\f2@throws\fP\h'|\n(41u'1.2 1039 .ta \n(80u \n(81u 1040 .nr 31 \n(.f 1041 .nr 35 1m 1042 \&\h'|\n(40u'\f2{@value}\fP\h'|\n(41u'1.4 1043 .ta \n(80u \n(81u 1044 .nr 31 \n(.f 1045 .nr 35 1m 1046 \&\h'|\n(40u'\f2@version\fP\h'|\n(41u'1.0 1047 .fc 1048 .nr T. 1 1049 .T# 1 1050 .35 1051 .rm a+ 1052 .TE 1053 .if \n-(b.=0 .nr c. \n(.c-\n(d.-44 1054 .LP 1055 カスタムタグについては、\-tag オプションを参照してください。 1056 .RS 3 1057 .TP 3 1058 @author\ name\-text 1059 \-author オプションが使用されている場合、指定された \f2name\-text\fP を含む [作成者] エントリを生成ドキュメントに追加します。1 つのドキュメンテーションコメントに複数の \f2@author\fP タグを含めることができます。1 つの \f2@author\fP タグに 1 つの名前を指定することも、複数の名前を指定することもできます。前者の場合は、Javadoc ツールによって名前と名前の間にコンマ (\f2,\fP) と空白が挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。 1060 .RE 1061 .LP 1062 詳細については、「タグを使用できる場所」および 1063 .na 1064 \f2@author タグのドキュメント\fP @ 1065 .fi 1066 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@authorを参照してください。 1067 .LP 1068 .RS 3 1069 .TP 3 1070 @deprecated\ deprecated\-text 注: @Deprecated 注釈を使って特定のプログラム要素を非推奨にできます。 1071 .RE 1072 .LP 1073 この API は動作し続けますが、この API を使用するべきではないことを示すコメントを追加します。Javadoc ツールは、 \f2deprecated\-text\fP を主説明の前に移動してイタリックにし、その前にボールドの警告「推奨されません。」を追加します。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 1074 .LP 1075 \f2deprecated\-text\fP の最初の文では、少なくとも、その API が推奨されなくなった時期と、代替使用するべき API を読者に提示する必要があります。Javadoc ツールは、この最初の文だけを、概要セクションと索引にコピーします。そのあとの文では、その API が推奨されない理由を説明することもできます。代わりのAPI を指し示す \f2{@link}\fP タグ ( Javadoc 1.2 以降の場合) を含めるべきです。 1076 .LP 1077 詳細については、 1078 .na 1079 \f2@deprecated タグのドキュメント\fP @ 1080 .fi 1081 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@deprecatedを参照してください。 1082 .RS 3 1083 .TP 2 1084 o 1085 Javadoc 1.2 以降では \f2{@link}\fP タグを使用します。これにより、必要な場所にインラインでリンクを作成できます。次に例を示します。 1086 .nf 1087 \f3 1088 .fl 1089 /** 1090 .fl 1091 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} 1092 .fl 1093 */ 1094 .fl 1095 1096 .fl 1097 \fP 1098 .fi 1099 .TP 2 1100 o 1101 Javadoc 1.1 の場合の標準形式は、 \f2@see\fP タグ (インラインは不可) を \f2@deprecated\fP タグごとに作成することです。 1102 .RE 1103 .LP 1104 推奨されないタグについての詳細は、 1105 .na 1106 \f2@deprecated タグ\fP @ 1107 .fi 1108 http://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/index.htmlのドキュメントを参照してください。 1109 .LP 1110 .RS 3 1111 .TP 3 1112 {@code\ text} 1113 \f2<code>{@literal}</code>\fP と同等です。 1114 .LP 1115 テキストを \f2HTML マークアップ\fP または \f2入れ子になった javadoc タグ\fP として解釈せずに、text をコードフォントで表示します。このため、ドキュメンテーションコメント内で通常の山括弧 (\f2<\fP および \f2>\fP) を HTML エンティティー (\f2<\fP および \f2>\fP) の代わりに使用できます。たとえば、パラメータの型 (\f2<Object>\fP)、不等号 (\f23 < 4\fP)、矢印 (\f2<\-\fP) などです。たとえば、次のドキュメンテーションコメント 1116 .nf 1117 \f3 1118 .fl 1119 \fP\f4{@code A<B>C}\fP\f3 1120 .fl 1121 1122 .fl 1123 \fP 1124 .fi 1125 .LP 1126 は、生成された HTML ページで、次のようにそのまま表示されます。 1127 .nf 1128 \f3 1129 .fl 1130 \fP\f4A<B>C\fP\f3 1131 .fl 1132 1133 .fl 1134 \fP 1135 .fi 1136 .LP 1137 ここで注目すべき点は、 \f2<B>\fP が太字として解釈されず、そのフォントはコードフォントになる、という点です。 1138 .LP 1139 コードフォントなしで同じ機能を実現するには、\f2{@literal}\fP を使用します。 1140 .LP 1141 .TP 3 1142 {@docRoot} 1143 生成されるページから見た、生成ドキュメントの (生成先の) ルートディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの下部から著作権のページにリンクします。 1144 .LP 1145 この \f2{@docRoot}\fP タグは、コマンド行でもドキュメンテーションコメント内でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 1146 .RS 3 1147 .TP 3 1148 1. 1149 コマンド行では、ヘッダー、フッター、またはボトムノートは次のように定義します。 1150 .nf 1151 \f3 1152 .fl 1153 javadoc \-bottom '<a href="{@docRoot}/copyright.html">Copyright</a>' 1154 .fl 1155 1156 .fl 1157 \fP 1158 .fi 1159 .LP 1160 注 \- \f2{@docRoot}\fP を Makefile 内でこのように利用する場合、一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする必要があります。たとえば、Inprise MAKE バージョン 5.2 を Windows 上で実行する場合は、 \f2{{@docRoot}} のように、中括弧を二重にする必要があります\fP。さらに、 \f2\-bottom\fP などのオプションに対する引数を、単一引用符ではなく二重引用符で囲む必要もあります ( \f2href\fP の引数を囲む引用符は省略)。 1161 .TP 3 1162 2. 1163 ドキュメンテーションコメントの中では、次のように使用します。 1164 .nf 1165 \f3 1166 .fl 1167 /** 1168 .fl 1169 * See the <a href="{@docRoot}/copyright.html">Copyright</a>. 1170 .fl 1171 */ 1172 .fl 1173 1174 .fl 1175 \fP 1176 .fi 1177 .RE 1178 .LP 1179 このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。次に例を示します。 1180 .nf 1181 \f3 1182 .fl 1183 <a href="{@docRoot}/copyright.html"> 1184 .fl 1185 1186 .fl 1187 \fP 1188 .fi 1189 .LP 1190 次のように解決されます。 1191 .nf 1192 \f3 1193 .fl 1194 <a href="../../copyright.html"> java/lang/Object.java の場合 1195 .fl 1196 1197 .fl 1198 \fP 1199 .fi 1200 .LP 1201 かつ 1202 .nf 1203 \f3 1204 .fl 1205 <a href="../../../copyright.html"> java/lang/ref/Reference.java の場合 1206 .fl 1207 1208 .fl 1209 \fP 1210 .fi 1211 .LP 1212 .TP 3 1213 @exception\ class\-name\ description 1214 \f2@exception\fP タグは \f2@throws\fP と同義です。 1215 .LP 1216 .TP 3 1217 {@inheritDoc}\ 1218 もっとも近い継承可能なクラスまたは実装可能なインタフェースから、このタグの現在のドキュメンテーションコメントに、ドキュメントを継承 (コピー) します。この機能により、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使って記述することができます。 1219 .LP 1220 このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。 1221 .RS 3 1222 .TP 2 1223 o 1224 メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされる 1225 .TP 2 1226 o 1227 メソッドの @return、@param、@throws タグのテキスト引数内。この場合、タグテキストは、上位階層の対応するタグからコピーされる 1228 .RE 1229 .LP 1230 継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。 1231 .LP 1232 .TP 3 1233 {@link\ package.class#member\ label} 1234 表示テキスト \f2label\fP とのインラインリンクを挿入します。label は、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 1235 .LP 1236 このタグは \f2@see\fP と非常によく似ています。どちらも、\f2package.class\fP\f2#\fP\f2member\fP と \f2label\fP の参照の仕方が同じで、有効な構文もまったく同じです。大きな違いは、 \f2{@link}\fP では、[関連項目] セクションにリンクが配置される代わりに、インラインのリンクが生成されるという点です。また、インラインテキストのほかの部分と区別するために、 \f2{@link}\fP タグの最初と最後に中括弧を記述します。ラベルの中で「}」を使う必要がある場合は、HTML エンティティーの「}」を使います。 1237 .LP 1238 1 文内で使用可能な \f2{@link}\fP タグの数に制限はありません。このタグは、ドキュメンテーションコメントの主説明部分、または @deprecated、@return、@param などの任意のタグのテキスト部分で使うことができます。 1239 .LP 1240 たとえば、次のコメントでは \f2getComponentAt(int, int)\fP メソッドを参照しています。 1241 .nf 1242 \f3 1243 .fl 1244 {@link #getComponentAt(int, int) getComponentAt} メソッドを使用します。 1245 .fl 1246 1247 .fl 1248 \fP 1249 .fi 1250 .LP 1251 標準ドックレットでは、上記のコメントから次の HTML が生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。 1252 .nf 1253 \f3 1254 .fl 1255 <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> メソッドを使用します。 1256 .fl 1257 1258 .fl 1259 \fP 1260 .fi 1261 .LP 1262 この HTML は、Web ページ上では次のように表示されます。 1263 .nf 1264 \f3 1265 .fl 1266 getComponentAt メソッドを使用します。 1267 .fl 1268 1269 .fl 1270 \fP 1271 .fi 1272 .LP 1273 \f2{@link}\fP を拡張してドキュメント化されないクラスへのリンクも可能にするには、\f2\-link\fP オプションを使用します。 1274 .LP 1275 詳細については、 1276 .na 1277 \f2{@link} タグのドキュメント\fP @ 1278 .fi 1279 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#{@link}を参照してください。 1280 .LP 1281 .TP 3 1282 {@linkplain\ package.class#member\ label} 1283 リンクのラベルがコードフォントではなくプレーンテキストで表示される点以外は \f2{@link}\fP と同じです。ラベルがプレーンテキストで記述されていると便利です。次の例を参照してください。例: 1284 .nf 1285 \f3 1286 .fl 1287 {@linkplain add() the overridden method} を参照してください。 1288 .fl 1289 1290 .fl 1291 \fP 1292 .fi 1293 .LP 1294 これは以下のように表示されます。 1295 .LP 1296 the overridden method を参照してください。 1297 .LP 1298 .TP 3 1299 {@literal\ text} 1300 テキストを HTML マークアップまたは入れ子になった javadoc タグとして解釈せずに、 \f2text\fP を表示します。このため、ドキュメンテーションコメント内で通常の山括弧 (\f2<\fP および \f2>\fP) を HTML エンティティー (\f2<\fP および \f2>\fP) の代わりに使用できます。たとえば、パラメータの型 (\f2<Object>\fP)、不等号 (\f23 < 4\fP)、矢印 (\f2<\-\fP) などです。たとえば、次のドキュメンテーションコメント 1301 .nf 1302 \f3 1303 .fl 1304 \fP\f4{@literal A<B>C}\fP\f3 1305 .fl 1306 1307 .fl 1308 \fP 1309 .fi 1310 .LP 1311 は、生成された HTML ページはブラウザで次のようにそのまま表示されます。 1312 .LP 1313 \f2\ \ \ \ \ \fPA<B>C 1314 .LP 1315 ここで注目すべき点は、 \f2<B>\fP が太字として解釈されず、そのフォントはコードフォントになる、という点です。 1316 .LP 1317 コードフォントで同じ機能を実現するには、\f2{@code}\fP を使用します。 1318 .LP 1319 .TP 3 1320 @param\ parameter\-name description 1321 指定された \f2parameter\-name\fP のあとに指定された \f2description\fP が続くパラメータを、[パラメータ] セクションに追加します。ドキュメンテーションコメントを記述するときには、 \f2description\fP を複数行にわたって記述することもできます。このタグは、メソッド、コンストラクタ、またはクラスの doc コメント内でのみ有効です。 1322 .LP 1323 \f2parameter\-name\fP は、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタのタイプパラメータの名前になります。山括弧でパラメータ名を囲むと、型パラメータを使用することを 指定します。 1324 .LP 1325 クラスの型パラメータの例: 1326 .nf 1327 \f3 1328 .fl 1329 /** 1330 .fl 1331 * @param <E> Type of element stored in a list 1332 .fl 1333 */ 1334 .fl 1335 public interface List<E> extends Collection<E> { 1336 .fl 1337 } 1338 .fl 1339 1340 .fl 1341 \fP 1342 .fi 1343 .LP 1344 メソッドの型パラメータの例: 1345 .nf 1346 \f3 1347 .fl 1348 /** 1349 .fl 1350 * @param string the string to be converted 1351 .fl 1352 * @param type the type to convert the string to 1353 .fl 1354 * @param <T> the type of the element 1355 .fl 1356 * @param <V> the value of the element 1357 .fl 1358 */ 1359 .fl 1360 <T, V extends T> V convert(String string, Class<T> type) { 1361 .fl 1362 } 1363 .fl 1364 1365 .fl 1366 \fP 1367 .fi 1368 .LP 1369 詳細については、 1370 .na 1371 \f2@param タグのドキュメント\fP @ 1372 .fi 1373 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@paramを参照してください。 1374 .LP 1375 .TP 3 1376 @return\ description 1377 [戻り値] セクションを追加して、 \f2description\fP のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。 1378 .LP 1379 詳細については、 1380 .na 1381 \f2@return タグのドキュメント\fP @ 1382 .fi 1383 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@returnを参照してください。 1384 .LP 1385 .TP 3 1386 @see\ reference 1387 「関連項目」見出しを追加し、 \f2reference を指すリンクか、またはテキストエントリを書き込みます\fP。ドキュメンテーションコメントには任意の数の \f2@see\fP タグを含めることができますが、それらはすべて同じ見出しの下にグループ化されます。 \f2@see\fP タグには、次の 3 種類の形式があります。もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバーに対するインラインリンクを文中に挿入する方法は、\f2{@link}\fP を参照してください。 1388 .RS 3 1389 .TP 3 1390 @see "string" 1391 \f2string のテキストエントリを追加します\fP。リンクは生成されません。 \f2string\fP は、書籍または URL ではアクセスできない情報の参照先です。Javadoc ツールは、最初の文字が二重引用符 (\f2"\fP) かどうかを調べて、この形式をほかの 2 つの形式と区別します。たとえば、 1392 .nf 1393 \f3 1394 .fl 1395 @see "The Java Programming Language" 1396 .fl 1397 1398 .fl 1399 \fP 1400 .fi 1401 .LP 1402 これは次のようなテキストを生成します。 1403 .RE 1404 .RE 1405 .RS 3 1406 .RS 3 1407 .RS 3 1408 .RS 3 1409 .TP 3 1410 関連項目: 1411 The Java Programming Language 1412 .RE 1413 .RE 1414 .TP 3 1415 @see <a href="URL#value">label</a> 1416 \f2URL\fP#\f2value\fP で定義されたとおりにリンクを追加します。 \f2URL\fP#\f2value\fP は相対 URL または絶対 URL です。Javadoc ツールは、最初の文字が「より小さい」記号 (\f2<\fP) かどうかを調べて、この形式をほかの 2 つの形式と区別します。たとえば、 1417 .nf 1418 \f3 1419 .fl 1420 @see <a href="spec.html#section">Java Spec</a> 1421 .fl 1422 \fP 1423 .fi 1424 これは次のようなリンクを生成します。 1425 .RS 3 1426 .TP 3 1427 関連項目: 1428 Java Spec 1429 .RE 1430 .TP 3 1431 @see\ package.class#member\ label 1432 可視のテキスト \f2label\fP を持つリンクを追加します。このリンクは、参照先となる、指定された Java 言語の名前のドキュメンテーションを指します。 \f2label\fP は省略可能です。label を省略すると、リンク先のメンバーの名前が適切に短縮されて表示されます。 「名前が表示される方法」を参照してください。\-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。 1433 .LP 1434 バージョン 1.2 だけは、ラベルではなく、名前が <code> HTML タグ内に自動的に表示されます。 1.2.2 からは、ラベルを使用するか、しないかにかかわらず、<code> は常に表示テキストを囲むかたちで、含まれます。 1435 .LP 1436 .RS 3 1437 .TP 2 1438 o 1439 \f4package.class\fP\f4#\fP\f4member\fP には、参照されている任意の有効なプログラム要素の名前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバー名ーの前のドットは、シャープ記号 (\f2#\fP) で置き換えます。 \f2class\fP は、任意のトップレベルまたは入れ子にされたクラスまたはインタフェースを表します。 \f2member\fP は、任意のコンストラクタ、メソッドまたはフィールド (入れ子にされたクラスまたはインタフェースではない) を表します。指定した名前が、ドキュメント化されているクラスに含まれている場合、Javadoc ツールは、その名前へのリンクを自動的に作成します。外部参照クラスへのリンクを作成するには、\f2\-link\fP オプションを使います。参照先のクラスに属していない名前のドキュメンテーションを参照するには、残り 2 つの \f2@see\fP 形式のうちのどちらかを使用します。この引数については、このあとの「名前の指定」で詳しく説明します。 1440 .TP 2 1441 o 1442 \f4label\fP は、省略可能なテキストで、リンクのラベルとして表示されます。 \f2label\fP には空白を含めることができます。 \f2label\fP を省略すると、\f2package.class.member\fP が、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。「名前が表示される方法」を参照してください。 1443 .TP 2 1444 o 1445 空白が、 \f2package.class\fP\f2#\fP\f2member\fP と \f2label\fP の間の区切り文字になります。括弧の内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。 1446 .RE 1447 .LP 1448 \f3例\fP \- この例では、 \f2@see\fP タグ ( \f2Character\fP クラス内) が String クラスの \f2equals\fP メソッド \f2を参照\fP しています。このタグには名前「\f2String#equals(Object)\fP」とラベル「\f2equals\fP」の両方の引数が含まれています。 1449 .nf 1450 \f3 1451 .fl 1452 /** 1453 .fl 1454 * @see String#equals(Object) equals 1455 .fl 1456 */ 1457 .fl 1458 \fP 1459 .fi 1460 標準ドックレットは、次のような HTML を生成します。 1461 .nf 1462 \f3 1463 .fl 1464 <dl> 1465 .fl 1466 <dt><b>See Also:</b> 1467 .fl 1468 <dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a> 1469 .fl 1470 </dl> 1471 .fl 1472 \fP 1473 .fi 1474 これは、ブラウザでは次のように表示され、ラベルがリンクテキストになります。 1475 .RS 3 1476 .TP 3 1477 関連項目: 1478 equals 1479 .RE 1480 .LP 1481 \f3名前の指定\fP \- この \f2package.class\fP\f2#\fP\f2member\fP という名前は、 \f2java.lang.String#toUpperCase()\fP のような完全修飾名にすることも、 \f2String#toUpperCase()\fP や \f2#toUpperCase()\fP のような非完全修飾名にすることもできます。名前が完全指定されていない場合、Javadoc ツールは、Java コンパイラの通常の検索順序でその名前を検索します。詳細は、このあとの「@see の検索順序」を参照してください。名前には、メソッドの複数の引数の間など、括弧の内側であれば空白を含めることができます。 1482 .LP 1483 「部分的に指定」した短い名前を指定することの利点は、入力する文字数が減ることや、ソースコードが読みやすくなることです。次の表に、さまざまな形式の名前を示します。ここで、 \f2Class\fP にはクラスまたはインタフェースを、 \f2Type\fP にはクラス、インタフェース、配列、または基本データ型を、 \f2method\fP にはメソッドまたはコンストラクタを、それぞれ指定できます。 1484 .LP 1485 .LP 1486 .TS 1487 .if \n+(b.=1 .nr d. \n(.c-\n(c.-1 1488 .de 35 1489 .ps \n(.s 1490 .vs \n(.vu 1491 .in \n(.iu 1492 .if \n(.u .fi 1493 .if \n(.j .ad 1494 .if \n(.j=0 .na 1495 .. 1496 .nf 1497 .nr #~ 0 1498 .if n .nr #~ 0.6n 1499 .ds #d .d 1500 .if \(ts\n(.z\(ts\(ts .ds #d nl 1501 .fc 1502 .nr 33 \n(.s 1503 .rm 80 1504 .nr 34 \n(.lu 1505 .eo 1506 .am 80 1507 .br 1508 .di a+ 1509 .35 1510 .ft \n(.f 1511 .ll \n(34u*1u/2u 1512 .if \n(.l<\n(80 .ll \n(80u 1513 .in 0 1514 \f4@see\fP\f3\ \fP\f4package.class#member\fP\f3 の一般的な形式\fP 1515 .br 1516 .di 1517 .nr a| \n(dn 1518 .nr a- \n(dl 1519 .. 1520 .ec \ 1521 .eo 1522 .am 80 1523 .br 1524 .di b+ 1525 .35 1526 .ft \n(.f 1527 .ll \n(34u*1u/2u 1528 .if \n(.l<\n(80 .ll \n(80u 1529 .in 0 1530 \f3現在のクラスのメンバーを参照する\fP 1531 .br 1532 \f2@see\fP\ \f2#\fP\f2フィールド\fP 1533 .br 1534 \f2@see\fP\ \f2#\fP\f2method(Type,\ Type,...)\fP 1535 .br 1536 \f2@see\fP\ \f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP 1537 .br 1538 \f2@see\fP\ \f2#\fP\f2constructor(Type,\ Type,...)\fP 1539 .br 1540 \f2@see\fP\ \f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP 1541 .br 1542 .di 1543 .nr b| \n(dn 1544 .nr b- \n(dl 1545 .. 1546 .ec \ 1547 .eo 1548 .am 80 1549 .br 1550 .di c+ 1551 .35 1552 .ft \n(.f 1553 .ll \n(34u*1u/2u 1554 .if \n(.l<\n(80 .ll \n(80u 1555 .in 0 1556 \f3現在の、またはインポートされたパッケージの別のクラスを参照する\fP 1557 .br 1558 \f2@see\fP\ \f2クラス\fP\f2#\fP\f2フィールド\fP 1559 .br 1560 \f2@see\fP\ \f2クラス\fP\f2#\fP\f2method(Type,\ Type,...)\fP 1561 .br 1562 \f2@see\fP\ \f2クラス\fP\f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP 1563 .br 1564 \f2@see\fP\ \f2クラス\fP\f2#\fP\f2constructor(Type,\ Type,...)\fP 1565 .br 1566 \f2@see\fP\ \f2クラス\fP\f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP 1567 .br 1568 \f2@see\fP\ \f2Class.NestedClass\fP 1569 .br 1570 \f2@see\fP\ \f2クラス\fP 1571 .br 1572 .di 1573 .nr c| \n(dn 1574 .nr c- \n(dl 1575 .. 1576 .ec \ 1577 .eo 1578 .am 80 1579 .br 1580 .di d+ 1581 .35 1582 .ft \n(.f 1583 .ll \n(34u*1u/2u 1584 .if \n(.l<\n(80 .ll \n(80u 1585 .in 0 1586 \f3別のパッケージの要素を参照する\fP\ (完全修飾) 1587 .br 1588 \f2@see\fP\ \f2package.Class\fP\f2#\fP\f2フィールド\fP 1589 .br 1590 \f2@see\fP\ \f2package.Class\fP\f2#\fP\f2method(Type,\ Type,...)\fP 1591 .br 1592 \f2@see\fP\ \f2package.Class\fP\f2#\fP\f2method(Type\ argname,\ Type\ argname,...)\fP 1593 .br 1594 \f2@see\fP\ \f2package.Class\fP\f2#\fP\f2constructor(Type,\ Type,...)\fP 1595 .br 1596 \f2@see\fP\ \f2package.Class\fP\f2#\fP\f2constructor(Type\ argname,\ Type\ argname,...)\fP 1597 .br 1598 \f2@see\fP\ \f2package.Class.NestedClass\fP 1599 .br 1600 \f2@see\fP\ \f2package.Class\fP 1601 .br 1602 \f2@see\fP\ \f2パッケージ\fP 1603 .br 1604 .di 1605 .nr d| \n(dn 1606 .nr d- \n(dl 1607 .. 1608 .ec \ 1609 .35 1610 .nf 1611 .ll \n(34u 1612 .nr 80 0 1613 .80 1614 .rm 80 1615 .nr 38 \n(a- 1616 .if \n(80<\n(38 .nr 80 \n(38 1617 .nr 38 \n(b- 1618 .if \n(80<\n(38 .nr 80 \n(38 1619 .nr 38 \n(c- 1620 .if \n(80<\n(38 .nr 80 \n(38 1621 .nr 38 \n(d- 1622 .if \n(80<\n(38 .nr 80 \n(38 1623 .35 1624 .nf 1625 .ll \n(34u 1626 .nr 38 1n 1627 .nr 79 0 1628 .nr 40 \n(79+(0*\n(38) 1629 .nr 80 +\n(40 1630 .nr TW \n(80 1631 .if t .if \n(TW>\n(.li .tm Table at line 1342 file Input is too wide - \n(TW units 1632 .fc 1633 .nr #T 0-1 1634 .nr #a 0-1 1635 .eo 1636 .de T# 1637 .ds #d .d 1638 .if \(ts\n(.z\(ts\(ts .ds #d nl 1639 .mk ## 1640 .nr ## -1v 1641 .ls 1 1642 .ls 1643 .. 1644 .ec 1645 .ne \n(a|u+\n(.Vu 1646 .if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v) 1647 .ta \n(80u 1648 .nr 31 \n(.f 1649 .nr 35 1m 1650 \&\h'|\n(40u' 1651 .mk ## 1652 .nr 31 \n(## 1653 .sp |\n(##u-1v 1654 .nr 37 \n(40u 1655 .in +\n(37u 1656 .a+ 1657 .in -\n(37u 1658 .mk 32 1659 .if \n(32>\n(31 .nr 31 \n(32 1660 .sp |\n(31u 1661 .ne \n(b|u+\n(.Vu 1662 .if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v) 1663 .ta \n(80u 1664 .nr 31 \n(.f 1665 .nr 35 1m 1666 \&\h'|\n(40u' 1667 .mk ## 1668 .nr 31 \n(## 1669 .sp |\n(##u-1v 1670 .nr 37 \n(40u 1671 .in +\n(37u 1672 .b+ 1673 .in -\n(37u 1674 .mk 32 1675 .if \n(32>\n(31 .nr 31 \n(32 1676 .sp |\n(31u 1677 .ne \n(c|u+\n(.Vu 1678 .if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v) 1679 .ta \n(80u 1680 .nr 31 \n(.f 1681 .nr 35 1m 1682 \&\h'|\n(40u' 1683 .mk ## 1684 .nr 31 \n(## 1685 .sp |\n(##u-1v 1686 .nr 37 \n(40u 1687 .in +\n(37u 1688 .c+ 1689 .in -\n(37u 1690 .mk 32 1691 .if \n(32>\n(31 .nr 31 \n(32 1692 .sp |\n(31u 1693 .ne \n(d|u+\n(.Vu 1694 .if (\n(d|+\n(#^-1v)>\n(#- .nr #- +(\n(d|+\n(#^-\n(#--1v) 1695 .ta \n(80u 1696 .nr 31 \n(.f 1697 .nr 35 1m 1698 \&\h'|\n(40u' 1699 .mk ## 1700 .nr 31 \n(## 1701 .sp |\n(##u-1v 1702 .nr 37 \n(40u 1703 .in +\n(37u 1704 .d+ 1705 .in -\n(37u 1706 .mk 32 1707 .if \n(32>\n(31 .nr 31 \n(32 1708 .sp |\n(31u 1709 .fc 1710 .nr T. 1 1711 .T# 1 1712 .35 1713 .rm a+ 1714 .rm b+ 1715 .rm c+ 1716 .rm d+ 1717 .TE 1718 .if \n-(b.=0 .nr c. \n(.c-\n(d.-58 1719 .LP 1720 上の表に対する補足事項を次に示します。 1721 .RS 3 1722 .TP 2 1723 o 1724 最初の種類の形式 (パッケージとクラスを省略) の場合、Javadoc ツールは、現在のクラスの階層だけを検索します。つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、または現在のクラスかインタフェースを囲んでいるクラスかインタフェースからメンバーを検索します (このあとの検索手順 1 ~ 3)。現在のパッケージのほかの部分や、ほかのパッケージは検索しません (検索手順 4 ~ 5)。 1725 .TP 2 1726 o 1727 メソッドまたはコンストラクタの指定時に、 \f2getValue\fP のように括弧なしの名前を使用した場合、同じ名前のフィールドが存在していなければ、Javadoc ツールによってその名前へのリンクが正しく作成されますが、括弧や引数の追加をユーザーに促すための警告メッセージが表示されます。このメソッドがオーバーロードされている場合、Javadoc ツールは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。 1728 .TP 2 1729 o 1730 入れ子になったクラスは、すべての形式について、 \f2outer\fP\f2.\fP\f2inner\fP として指定する必要があります。単純に \f2inner\fP とはしないでください。 1731 .TP 2 1732 o 1733 すでに述べたように、\f2クラスとメンバーとの間の区切り文字としては、\fPドット (\f2.\fP) ではなくシャープ文字 (#) を使用します。このように指定すると、Javadoc ツールは、あいまいさを解決できます。ドットは、クラス、入れ子にされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されます。ただし、Javadoc ツールでは一般に許容範囲が広く、あいまいさがなければ、ドットでも正しく解析されます。その場合でも警告は表示されます。 1734 .RE 1735 .LP 1736 \f3@see の検索順序\fP \- Javadoc ツールは、ソースファイル (.java)、パッケージファイル (package.html または package\-info.java) または概要ファイル (overview.html) に含まれる \f2@see\fP タグを処理します。後者の 2 つのファイルでは、完全指定の名前を \f2@see\fP タグに指定しなければなりません。ソースファイルでは、完全指定の名前、または部分指定の名前を指定できます。 1737 .LP 1738 Javadoc ツールは、完全指定でない名前が記述された \f2@see\fP タグを \f2.java ファイル内で見つけると、\fP Java コンパイラと同じ順序で指定された名前を検索します。 ただし、Javadoc ツールは、特定の名前空間のあいまいさを検出しません。 これは、ソースコードにこれらのエラーが存在していないことを前提としているためです。この検索順序は、\f2Java 言語仕様\fPで正式に定義されています。Javadoc ツールは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてから名前を検索します。具体的には、次の順序で検索します。 1739 .RS 3 1740 .TP 3 1741 1. 1742 現在のクラスまたはインタフェース 1743 .TP 3 1744 2. 1745 外側を囲んでいるクラスとインタフェース (もっとも近いものから検索) 1746 .TP 3 1747 3. 1748 スーパークラスとスーパーインタフェース (もっとも近いものから検索) 1749 .TP 3 1750 4. 1751 現在のパッケージ 1752 .TP 3 1753 5. 1754 インポートされているパッケージ、クラス、およびインタフェース (import 文の順序に従って検索) 1755 .RE 1756 .LP 1757 Javadoc ツールは、各クラスについて手順 1 ~ 3 を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にそのクラスを囲んでいるクラス E を検索し、その次に E のスーパークラスを検索し、さらにその次に E を囲んでいるクラスを検索します。 手順 4 と 5 では、1 つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません。その順序は、個々のコンパイラによって異なります。手順 5 では、Javadoc ツールは、java.lang を検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。 1758 .LP 1759 Javadoc ツールは、必ずしもサブクラスを検索するとは限りません。また、javadoc の実行中にほかのパッケージのドキュメントが生成される場合でも、ほかのパッケージを検索しません。たとえば、 \f2@see\fP タグが \f2java.awt.event.KeyEvent\fP クラス内に含まれていて、 \f2java.awt\fP パッケージ内のある名前を参照していても、そのクラス内でそのパッケージがインポートされないかぎり、javadoc はそのパッケージ内での検索を行いません。 1760 .LP 1761 \f3名前が表示される方法\fP \- \f2label\fP を省略した場合は、\f2package.class.member\fP が表示されます。一般に、package.class.member は、現在のクラスおよびパッケージに応じて適切に短縮されます。「短縮される」とは、必要最小限の名前だけが表示されるということです。たとえば、 \f2String.toUpperCase()\fP メソッドに、同じクラスのメンバーへの参照とほかのクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースだけです (次の表を参照)。 1762 .LP 1763 パッケージ名を広域的に削除するには、\-noqualifier を使用します。 1764 .br 1765 .LP 1766 .TS 1767 .if \n+(b.=1 .nr d. \n(.c-\n(c.-1 1768 .de 35 1769 .ps \n(.s 1770 .vs \n(.vu 1771 .in \n(.iu 1772 .if \n(.u .fi 1773 .if \n(.j .ad 1774 .if \n(.j=0 .na 1775 .. 1776 .nf 1777 .nr #~ 0 1778 .if n .nr #~ 0.6n 1779 .ds #d .d 1780 .if \(ts\n(.z\(ts\(ts .ds #d nl 1781 .fc 1782 .nr 33 \n(.s 1783 .rm 80 81 82 1784 .nr 34 \n(.lu 1785 .eo 1786 .am 81 1787 .br 1788 .di a+ 1789 .35 1790 .ft \n(.f 1791 .ll \n(34u*1u/4u 1792 .if \n(.l<\n(81 .ll \n(81u 1793 .in 0 1794 \f4String.toUpperCase() での例\fP 1795 .br 1796 .di 1797 .nr a| \n(dn 1798 .nr a- \n(dl 1799 .. 1800 .ec \ 1801 .eo 1802 .am 80 1803 .br 1804 .di b+ 1805 .35 1806 .ft \n(.f 1807 .ll \n(34u*1u/4u 1808 .if \n(.l<\n(80 .ll \n(80u 1809 .in 0 1810 \f2@see\fP タグが同じクラス、同じパッケージのメンバーを参照している 1811 .br 1812 .di 1813 .nr b| \n(dn 1814 .nr b- \n(dl 1815 .. 1816 .ec \ 1817 .eo 1818 .am 82 1819 .br 1820 .di c+ 1821 .35 1822 .ft \n(.f 1823 .ll \n(34u*1u/4u 1824 .if \n(.l<\n(82 .ll \n(82u 1825 .in 0 1826 \f2toLowerCase()\fP (クラス名は省略) 1827 .br 1828 .di 1829 .nr c| \n(dn 1830 .nr c- \n(dl 1831 .. 1832 .ec \ 1833 .eo 1834 .am 80 1835 .br 1836 .di d+ 1837 .35 1838 .ft \n(.f 1839 .ll \n(34u*1u/4u 1840 .if \n(.l<\n(80 .ll \n(80u 1841 .in 0 1842 \f2@see\fP タグが異なるクラス、同じパッケージのメンバーを参照している 1843 .br 1844 .di 1845 .nr d| \n(dn 1846 .nr d- \n(dl 1847 .. 1848 .ec \ 1849 .eo 1850 .am 81 1851 .br 1852 .di e+ 1853 .35 1854 .ft \n(.f 1855 .ll \n(34u*1u/4u 1856 .if \n(.l<\n(81 .ll \n(81u 1857 .in 0 1858 \f2@see Character#toLowerCase(char)\fP 1859 .br 1860 .di 1861 .nr e| \n(dn 1862 .nr e- \n(dl 1863 .. 1864 .ec \ 1865 .eo 1866 .am 82 1867 .br 1868 .di f+ 1869 .35 1870 .ft \n(.f 1871 .ll \n(34u*1u/4u 1872 .if \n(.l<\n(82 .ll \n(82u 1873 .in 0 1874 \f2Character.toLowerCase(char)\fP (パッケージ名は省略し、クラス名を含む) 1875 .br 1876 .di 1877 .nr f| \n(dn 1878 .nr f- \n(dl 1879 .. 1880 .ec \ 1881 .eo 1882 .am 80 1883 .br 1884 .di g+ 1885 .35 1886 .ft \n(.f 1887 .ll \n(34u*1u/4u 1888 .if \n(.l<\n(80 .ll \n(80u 1889 .in 0 1890 \f2@see\fP タグが異なるクラス、異なるパッケージのメンバーを参照している 1891 .br 1892 .di 1893 .nr g| \n(dn 1894 .nr g- \n(dl 1895 .. 1896 .ec \ 1897 .eo 1898 .am 81 1899 .br 1900 .di h+ 1901 .35 1902 .ft \n(.f 1903 .ll \n(34u*1u/4u 1904 .if \n(.l<\n(81 .ll \n(81u 1905 .in 0 1906 \f2@see java.io.File#exists()\fP 1907 .br 1908 .di 1909 .nr h| \n(dn 1910 .nr h- \n(dl 1911 .. 1912 .ec \ 1913 .eo 1914 .am 82 1915 .br 1916 .di i+ 1917 .35 1918 .ft \n(.f 1919 .ll \n(34u*1u/4u 1920 .if \n(.l<\n(82 .ll \n(82u 1921 .in 0 1922 \f2java.io.File.exists()\fP (パッケージ名とクラス名を含む) 1923 .br 1924 .di 1925 .nr i| \n(dn 1926 .nr i- \n(dl 1927 .. 1928 .ec \ 1929 .35 1930 .nf 1931 .ll \n(34u 1932 .nr 80 0 1933 .nr 38 \w\f3参照の種類\fP 1934 .if \n(80<\n(38 .nr 80 \n(38 1935 .80 1936 .rm 80 1937 .nr 38 \n(b- 1938 .if \n(80<\n(38 .nr 80 \n(38 1939 .nr 38 \n(d- 1940 .if \n(80<\n(38 .nr 80 \n(38 1941 .nr 38 \n(g- 1942 .if \n(80<\n(38 .nr 80 \n(38 1943 .nr 81 0 1944 .nr 38 \w\f2@see String#toLowerCase()\fP 1945 .if \n(81<\n(38 .nr 81 \n(38 1946 .81 1947 .rm 81 1948 .nr 38 \n(a- 1949 .if \n(81<\n(38 .nr 81 \n(38 1950 .nr 38 \n(e- 1951 .if \n(81<\n(38 .nr 81 \n(38 1952 .nr 38 \n(h- 1953 .if \n(81<\n(38 .nr 81 \n(38 1954 .nr 82 0 1955 .nr 38 \w\f3表示される名前\fP 1956 .if \n(82<\n(38 .nr 82 \n(38 1957 .82 1958 .rm 82 1959 .nr 38 \n(c- 1960 .if \n(82<\n(38 .nr 82 \n(38 1961 .nr 38 \n(f- 1962 .if \n(82<\n(38 .nr 82 \n(38 1963 .nr 38 \n(i- 1964 .if \n(82<\n(38 .nr 82 \n(38 1965 .35 1966 .nf 1967 .ll \n(34u 1968 .nr 38 1n 1969 .nr 79 0 1970 .nr 40 \n(79+(0*\n(38) 1971 .nr 80 +\n(40 1972 .nr 41 \n(80+(3*\n(38) 1973 .nr 81 +\n(41 1974 .nr 42 \n(81+(3*\n(38) 1975 .nr 82 +\n(42 1976 .nr TW \n(82 1977 .if t .if \n(TW>\n(.li .tm Table at line 1418 file Input is too wide - \n(TW units 1978 .fc 1979 .nr #T 0-1 1980 .nr #a 0-1 1981 .eo 1982 .de T# 1983 .ds #d .d 1984 .if \(ts\n(.z\(ts\(ts .ds #d nl 1985 .mk ## 1986 .nr ## -1v 1987 .ls 1 1988 .ls 1989 .. 1990 .ec 1991 .ne \n(a|u+\n(.Vu 1992 .if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v) 1993 .ta \n(80u \n(81u \n(82u 1994 .nr 31 \n(.f 1995 .nr 35 1m 1996 \&\h'|\n(40u'\f3参照の種類\fP\h'|\n(41u'\h'|\n(42u'\f3表示される名前\fP 1997 .mk ## 1998 .nr 31 \n(## 1999 .sp |\n(##u-1v 2000 .nr 37 \n(41u 2001 .in +\n(37u 2002 .a+ 2003 .in -\n(37u 2004 .mk 32 2005 .if \n(32>\n(31 .nr 31 \n(32 2006 .sp |\n(31u 2007 .ne \n(b|u+\n(.Vu 2008 .ne \n(c|u+\n(.Vu 2009 .if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v) 2010 .if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v) 2011 .ta \n(80u \n(81u \n(82u 2012 .nr 31 \n(.f 2013 .nr 35 1m 2014 \&\h'|\n(40u'\h'|\n(41u'\f2@see String#toLowerCase()\fP\h'|\n(42u' 2015 .mk ## 2016 .nr 31 \n(## 2017 .sp |\n(##u-1v 2018 .nr 37 \n(40u 2019 .in +\n(37u 2020 .b+ 2021 .in -\n(37u 2022 .mk 32 2023 .if \n(32>\n(31 .nr 31 \n(32 2024 .sp |\n(##u-1v 2025 .nr 37 \n(42u 2026 .in +\n(37u 2027 .c+ 2028 .in -\n(37u 2029 .mk 32 2030 .if \n(32>\n(31 .nr 31 \n(32 2031 .sp |\n(31u 2032 .ne \n(d|u+\n(.Vu 2033 .ne \n(e|u+\n(.Vu 2034 .ne \n(f|u+\n(.Vu 2035 .if (\n(d|+\n(#^-1v)>\n(#- .nr #- +(\n(d|+\n(#^-\n(#--1v) 2036 .if (\n(e|+\n(#^-1v)>\n(#- .nr #- +(\n(e|+\n(#^-\n(#--1v) 2037 .if (\n(f|+\n(#^-1v)>\n(#- .nr #- +(\n(f|+\n(#^-\n(#--1v) 2038 .ta \n(80u \n(81u \n(82u 2039 .nr 31 \n(.f 2040 .nr 35 1m 2041 \&\h'|\n(40u'\h'|\n(41u'\h'|\n(42u' 2042 .mk ## 2043 .nr 31 \n(## 2044 .sp |\n(##u-1v 2045 .nr 37 \n(40u 2046 .in +\n(37u 2047 .d+ 2048 .in -\n(37u 2049 .mk 32 2050 .if \n(32>\n(31 .nr 31 \n(32 2051 .sp |\n(##u-1v 2052 .nr 37 \n(41u 2053 .in +\n(37u 2054 .e+ 2055 .in -\n(37u 2056 .mk 32 2057 .if \n(32>\n(31 .nr 31 \n(32 2058 .sp |\n(##u-1v 2059 .nr 37 \n(42u 2060 .in +\n(37u 2061 .f+ 2062 .in -\n(37u 2063 .mk 32 2064 .if \n(32>\n(31 .nr 31 \n(32 2065 .sp |\n(31u 2066 .ne \n(g|u+\n(.Vu 2067 .ne \n(h|u+\n(.Vu 2068 .ne \n(i|u+\n(.Vu 2069 .if (\n(g|+\n(#^-1v)>\n(#- .nr #- +(\n(g|+\n(#^-\n(#--1v) 2070 .if (\n(h|+\n(#^-1v)>\n(#- .nr #- +(\n(h|+\n(#^-\n(#--1v) 2071 .if (\n(i|+\n(#^-1v)>\n(#- .nr #- +(\n(i|+\n(#^-\n(#--1v) 2072 .ta \n(80u \n(81u \n(82u 2073 .nr 31 \n(.f 2074 .nr 35 1m 2075 \&\h'|\n(40u'\h'|\n(41u'\h'|\n(42u' 2076 .mk ## 2077 .nr 31 \n(## 2078 .sp |\n(##u-1v 2079 .nr 37 \n(40u 2080 .in +\n(37u 2081 .g+ 2082 .in -\n(37u 2083 .mk 32 2084 .if \n(32>\n(31 .nr 31 \n(32 2085 .sp |\n(##u-1v 2086 .nr 37 \n(41u 2087 .in +\n(37u 2088 .h+ 2089 .in -\n(37u 2090 .mk 32 2091 .if \n(32>\n(31 .nr 31 \n(32 2092 .sp |\n(##u-1v 2093 .nr 37 \n(42u 2094 .in +\n(37u 2095 .i+ 2096 .in -\n(37u 2097 .mk 32 2098 .if \n(32>\n(31 .nr 31 \n(32 2099 .sp |\n(31u 2100 .fc 2101 .nr T. 1 2102 .T# 1 2103 .35 2104 .rm a+ 2105 .rm b+ 2106 .rm c+ 2107 .rm d+ 2108 .rm e+ 2109 .rm f+ 2110 .rm g+ 2111 .rm h+ 2112 .rm i+ 2113 .TE 2114 .if \n-(b.=0 .nr c. \n(.c-\n(d.-28 2115 .LP 2116 \f3@see の例\fP 2117 .br 2118 右側のコメントは、 \f2@see\fP タグが \f2java.applet.Applet\fP などの別のパッケージのクラス内にある場合に、名前がどのように表示されるかを示しています。 2119 .nf 2120 \f3 2121 .fl 2122 関連項目: 2123 .fl 2124 @see java.lang.String // String \fP\f3 2125 .fl 2126 @see java.lang.String The String class // The String class \fP\f3 2127 .fl 2128 @see String // String \fP\f3 2129 .fl 2130 @see String#equals(Object) // String.equals(Object) \fP\f3 2131 .fl 2132 @see String#equals // String.equals(java.lang.Object) \fP\f3 2133 .fl 2134 @see java.lang.Object#wait(long) // java.lang.Object.wait(long) \fP\f3 2135 .fl 2136 @see Character#MAX_RADIX // Character.MAX_RADIX \fP\f3 2137 .fl 2138 @see <a href="spec.html">Java Spec</a> // Java Spec \fP\f3 2139 .fl 2140 @see "The Java Programming Language" // "The Java Programming Language" \fP\f3 2141 .fl 2142 \fP 2143 .fi 2144 \f2@see\fP を拡張してドキュメント化されないクラスへのリンクも可能にするには、\f2\-link\fP オプションを使用します。 2145 .LP 2146 詳細については、 2147 .na 2148 \f2@see タグのドキュメント\fP @ 2149 .fi 2150 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@seeを参照してください。 2151 .RE 2152 .RE 2153 .LP 2154 .RS 3 2155 .TP 3 2156 @serial\ field\-description | include | exclude 2157 デフォルトの直列化可能フィールドのドキュメンテーションコメントで使用します。 2158 .LP 2159 \f2field\-description\fP (省略可能) では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要に応じて、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式のページに追加します。 2160 .LP 2161 クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。 2162 .LP 2163 \f2include\fP および \f2exclude\fP 引数は、直列化された形式のページにクラスまたはパッケージを含めるか除外するかを示します。これらの引数には、次のような効果があります。 2164 .RS 3 2165 .TP 2 2166 o 2167 \f2Serializable\fP を実装している public または protected クラスは、そのクラス (またはそのパッケージ) が \f2@serial exclude\fP としてマークされていないかぎり、含められます。 2168 .TP 2 2169 o 2170 \f2Serializable\fP を実装している private または package\-private クラスは、そのクラス (またはそのパッケージ) が \f2@serial include\fP として マークされていないかぎり、除外されます。 2171 .RE 2172 .LP 2173 例: \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 としてマークされています。 2174 .LP 2175 クラスレベルで指定された @serial タグは、パッケージレベルで指定された @serial タグをオーバーライドします。 2176 .LP 2177 これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節 2178 .na 2179 \f2「クラスの直列化可能なフィールドおよびデータの文書化」\fP @ 2180 .fi 2181 http://java.sun.com/javase/6/docs/platform/serialization/spec/serial\-arch.htmlを参照してください。また、 2182 .na 2183 \f2「直列化の FAQ」\fP @ 2184 .fi 2185 http://java.sun.com/javase/technologies/core/basic/serializationFAQ.jsp#javadoc_warn_missingも参照してください。この FAQ には、「\-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、 2186 .na 2187 \f2「Sun の仕様」\fP @ 2188 .fi 2189 http://java.sun.com/j2se/javadoc/writingapispecs/serialized\-criteria.htmlも参照してください。 2190 .LP 2191 .TP 3 2192 @serialField\ field\-name\ field\-type\ field\-description 2193 Serializable \f2クラスの\fP serialPersistentFields \f2メンバーの\fP ObjectStreamField コンポーネント \f2をドキュメント化\fP します。1 つの \f2@serialField\fP タグを各 \f2ObjectStreamField\fP コンポーネントで使用すべきです。 2194 .LP 2195 .TP 3 2196 @serialData\ data\-description 2197 \f2data\-description\fP は、直列化された形式でのデータの型と順序を説明するテキストです。具体的に言うと、このデータには、 \f2writeObject\fP メソッドによって書き込まれる省略可能なデータ、および \f2Externalizable.writeExternal\fP メソッドによって書き込まれるすべてのデータ (基底クラスも含む) が含まれます。 2198 .LP 2199 \f2@serialData\fP タグは、 \f2writeObject\fP、 \f2readObject\fP、 \f2writeExternal\fP、 \f2readExternal\fP、 \f2writeReplace\fP、および \f2readResolve\fP メソッドのドキュメンテーションコメント内で使用できます。 2200 .LP 2201 .TP 3 2202 @since\ since\-text 2203 生成ドキュメントに [導入されたバージョン] 見出しを追加し、指定された \f2since\-text\fP を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、 \f2since\-text に示されたソフトウェアリリース以降、存在していることを意味します\fP。たとえば、 2204 .nf 2205 \f3 2206 .fl 2207 @since 1.5 2208 .fl 2209 2210 .fl 2211 \fP 2212 .fi 2213 .LP 2214 Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。 2215 .LP 2216 .TP 3 2217 @throws\ class\-name\ description 2218 \f2@throws\fP タグと \f2@exception\fP タグは同義です。生成ドキュメントに「例外」小見出しを追加して、 \f2class\-name\fP および \f2description\fP のテキストを書き込みます。 \f2class\-name\fP は、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタの doc コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、Javadoc ツールは、検索順序に従ってクラスを探します。同じまたは異なる例外の doc コメントで、複数の \f2@throws\fP タグを使用できます。 2219 .LP 2220 すべてのチェック済み例外がドキュメント化されるようにするために、 \f2@throws\fP タグが throws 節内の例外用に存在しない場合は、@throws タグのあるドキュメントであるかのように、Javadoc ツールによって例外が HTML 出力に説明なしで自動的に追加されます。 2221 .LP 2222 オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、 \f2@throws\fP ドキュメンテーションがそのメソッドからサブクラスにコピーされます。インタフェースメソッドから実装メソッドにコピーされる場合も同様です。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。 2223 .LP 2224 詳細については、 2225 .na 2226 \f2@throws タグのドキュメント\fP @ 2227 .fi 2228 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@exceptionを参照してください。 2229 .LP 2230 .TP 3 2231 {@value\ package.class#field} 2232 \f2{@value}\fP が静的フィールドの doc コメントで 引数なしで使用されている場合、その定数の値が表示されます。 2233 .nf 2234 \f3 2235 .fl 2236 /** 2237 .fl 2238 * The value of this constant is {@value}. 2239 .fl 2240 */ 2241 .fl 2242 public static final String SCRIPT_START = "<script>" 2243 .fl 2244 2245 .fl 2246 \fP 2247 .fi 2248 .LP 2249 任意のドキュメンテーションコメント内で引数 \f2package.class#field\fP ありで使用された場合は、その指定された定数の値が表示されます。 2250 .nf 2251 \f3 2252 .fl 2253 /** 2254 .fl 2255 * Evaluates the script starting with {@value #SCRIPT_START}. 2256 .fl 2257 */ 2258 .fl 2259 public String evalScript(String script) { 2260 .fl 2261 } 2262 .fl 2263 2264 .fl 2265 \fP 2266 .fi 2267 .LP 2268 引数 \f2package.class#field\fP は、@see 引数と同一の形式になります。ただし、メンバーが静的フィールドになければならない点が異なります。 2269 .LP 2270 これらの定数での値は、 2271 .na 2272 \f2定数フィールド値\fP @ 2273 .fi 2274 http://java.sun.com/javase/6/docs/api/constant\-values.htmlページにも表示されます。 2275 .LP 2276 .TP 3 2277 @version\ version\-text 2278 \-version オプションが使用されると、生成ドキュメントに [バージョン] 小見出しを追加し、指定された \f2version\-text\fP を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。これに対し、@since は、このコードが導入されたバージョン番号を保持します。 \f2version\-text\fP には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。 2279 .LP 2280 1 つのドキュメンテーションコメントに複数の \f2@version\fP タグを含めることができます。意味が失われない範囲内で、1 つの \f2@version\fP タグに 1 つのバージョン番号を指定することも、複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって名前と名前の間にコンマ (\f2,\fP) と空白が挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要があるときは、1 つのタグに複数の名前を指定してください。 2281 .LP 2282 詳細については、 2283 .na 2284 \f2@version タグのドキュメント\fP @ 2285 .fi 2286 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#@versionを参照してください。 2287 .RE 2288 .SS 2289 タグを使用できる場所 2290 .LP 2291 ここでは、タグを使用できる場所について説明します。すべてのドキュメンテーションコメントで使用可能なタグは次のとおりです。 \f2@see\fP、 \f2@since\fP、 \f2@deprecated\fP、 \f2{@link}\fP、 \f2{@linkplain}\fP、および \f2{@docroot}\fP。 2292 .SS 2293 概要のドキュメンテーションタグ 2294 .LP 2295 概要タグは、概要ページのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは、通常 \f2overview.html\fP という名前のソースファイル内にあります。 ほかのドキュメンテーションコメントの場合と同様に、これらのタグは、主説明のあとで使う必要があります。 2296 .LP 2297 \f3注\fP \- バージョン 1.2 では、概要ドキュメント内の \f2{@link}\fP タグにバグがあります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、 \f2{@docRoot}\fP タグは、概要ドキュメント内では動作しません。 2298 .LP 2299 \f3概要タグ\fP 2300 .RS 3 2301 .TP 2 2302 o 2303 \f2@see\fP 2304 .TP 2 2305 o 2306 \f2@since\fP 2307 .TP 2 2308 o 2309 \f2@author\fP 2310 .TP 2 2311 o 2312 \f2@version\fP 2313 .TP 2 2314 o 2315 \f2{@link}\fP 2316 .TP 2 2317 o 2318 \f2{@linkplain}\fP 2319 .TP 2 2320 o 2321 \f2{@docRoot}\fP 2322 .RE 2323 .SS 2324 パッケージドキュメンテーションタグ 2325 .LP 2326 パッケージタグは、パッケージのドキュメンテーションコメントで使用できるタグです。このドキュメンテーションコメントは \f2package.html\fP または \f2package\-info.java\fP という名前のソースファイル内にあります。ここで使用できる \f2@serial\fP タグは、 \f2include\fP または \f2exclude\fP 引数が指定されたものだけです。 2327 .LP 2328 \f3パッケージタグ\fP 2329 .RS 3 2330 .TP 2 2331 o 2332 \f2@see\fP 2333 .TP 2 2334 o 2335 \f2@since\fP 2336 .TP 2 2337 o 2338 \f2@serial\fP 2339 .TP 2 2340 o 2341 \f2@author\fP 2342 .TP 2 2343 o 2344 \f2@version\fP 2345 .TP 2 2346 o 2347 \f2{@link}\fP 2348 .TP 2 2349 o 2350 \f2{@linkplain}\fP 2351 .TP 2 2352 o 2353 \f2{@docRoot}\fP 2354 .RE 2355 .SS 2356 クラスおよびインタフェースドキュメンテーションタグ 2357 .LP 2358 次に、クラスまたはインタフェースのドキュメンテーションコメントで使用できるタグを示します。ここで使用できる \f2@serial\fP タグは、 \f2include\fP または \f2exclude\fP 引数が指定されたものだけです。 2359 .LP 2360 \f3クラスおよびインタフェースタグ\fP 2361 .RS 3 2362 .TP 2 2363 o 2364 \f2@see\fP 2365 .TP 2 2366 o 2367 \f2@since\fP 2368 .TP 2 2369 o 2370 \f2@deprecated\fP 2371 .TP 2 2372 o 2373 \f2@serial\fP 2374 .TP 2 2375 o 2376 \f2@author\fP 2377 .TP 2 2378 o 2379 \f2@version\fP 2380 .TP 2 2381 o 2382 \f2{@link}\fP 2383 .TP 2 2384 o 2385 \f2{@linkplain}\fP 2386 .TP 2 2387 o 2388 \f2{@docRoot}\fP 2389 .RE 2390 \f3次にクラスコメントの例を示します。\fP 2391 .nf 2392 \f3 2393 .fl 2394 /** 2395 .fl 2396 * A class representing a window on the screen. 2397 .fl 2398 * For example: 2399 .fl 2400 * <pre> 2401 .fl 2402 * Window win = new Window(parent); 2403 .fl 2404 * win.show(); 2405 .fl 2406 * </pre> 2407 .fl 2408 * 2409 .fl 2410 * @author Sami Shaio 2411 .fl 2412 * @version 1.13, 06/08/06 2413 .fl 2414 * @see java.awt.BaseWindow 2415 .fl 2416 * @see java.awt.Button 2417 .fl 2418 */ 2419 .fl 2420 class Window extends BaseWindow { 2421 .fl 2422 ... 2423 .fl 2424 } 2425 .fl 2426 \fP 2427 .fi 2428 .SS 2429 フィールドドキュメンテーションタグ 2430 .LP 2431 次に、フィールドのドキュメンテーションコメントで使用できるタグを示します。 2432 .LP 2433 \f3フィールドタグ\fP 2434 .RS 3 2435 .TP 2 2436 o 2437 \f2@see\fP 2438 .TP 2 2439 o 2440 \f2@since\fP 2441 .TP 2 2442 o 2443 \f2@deprecated\fP 2444 .TP 2 2445 o 2446 \f2@serial\fP 2447 .TP 2 2448 o 2449 \f2@serialField\fP 2450 .TP 2 2451 o 2452 \f2{@link}\fP 2453 .TP 2 2454 o 2455 \f2{@linkplain}\fP 2456 .TP 2 2457 o 2458 \f2{@docRoot}\fP 2459 .TP 2 2460 o 2461 \f2{@value}\fP 2462 .RE 2463 \f3次にフィールドコメントの例を示します。\fP 2464 .nf 2465 \f3 2466 .fl 2467 /** 2468 .fl 2469 * The X\-coordinate of the component. 2470 .fl 2471 * 2472 .fl 2473 * @see #getLocation() 2474 .fl 2475 */ 2476 .fl 2477 int x = 1263732; 2478 .fl 2479 \fP 2480 .fi 2481 .SS 2482 コンストラクタおよびメソッドドキュメンテーションタグ 2483 .LP 2484 次に、コンストラクタまたはメソッドのドキュメンテーションコメントで使用できるタグを示します。ただし、 \f2@return\fP はコンストラクタでは使用できず、 \f2{@inheritDoc}\fP には特定の制限があります。 \f2@serialData\fP タグは特定の直列化メソッドの doc コメントでのみ使用できます。 2485 .LP 2486 \f3メソッドおよびコンストラクタタグ\fP 2487 .RS 3 2488 .TP 2 2489 o 2490 \f2@see\fP 2491 .TP 2 2492 o 2493 \f2@since\fP 2494 .TP 2 2495 o 2496 \f2@deprecated\fP 2497 .TP 2 2498 o 2499 \f2@param\fP 2500 .TP 2 2501 o 2502 \f2@return\fP 2503 .TP 2 2504 o 2505 \f2@throws\fP と \f2@exception\fP 2506 .TP 2 2507 o 2508 \f2@serialData\fP 2509 .TP 2 2510 o 2511 \f2{@link}\fP 2512 .TP 2 2513 o 2514 \f2{@linkplain}\fP 2515 .TP 2 2516 o 2517 \f2{@inheritDoc}\fP 2518 .TP 2 2519 o 2520 \f2{@docRoot}\fP 2521 .RE 2522 \f3次にメソッドのドキュメンテーションコメントの例を示します。\fP 2523 .nf 2524 \f3 2525 .fl 2526 /** 2527 .fl 2528 * Returns the character at the specified index. An index 2529 .fl 2530 * ranges from <code>0</code> to <code>length() \- 1</code>. 2531 .fl 2532 * 2533 .fl 2534 * @param index the index of the desired character. 2535 .fl 2536 * @return the desired character. 2537 .fl 2538 * @exception StringIndexOutOfRangeException 2539 .fl 2540 * if the index is not in the range <code>0</code> 2541 .fl 2542 * to <code>length()\-1</code>. 2543 .fl 2544 * @see java.lang.Character#charValue() 2545 .fl 2546 */ 2547 .fl 2548 public char charAt(int index) { 2549 .fl 2550 ... 2551 .fl 2552 } 2553 .fl 2554 \fP 2555 .fi 2556 .SH "オプション" 2557 .LP 2558 javadoc ツールは、ドックレットを使って出力を決定します。Javadoc ツールは、\-doclet オプションでカスタムドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使います。Javadoc ツールには、任意のドックレットとともに使用できるコマンド行オプションがあります。これらのオプションについては、このあとの「Javadoc オプション」で説明します。標準ドックレットでは、このほかに、いくつかの追加のコマンド行オプションが提供されます。これらのオプションについては、そのあとの「標準ドックレットが提供するオプション」で説明します。どのオプション名も、大文字と小文字が区別されません。ただし、オプションの引数では、大文字と小文字が区別されます。 2559 .LP 2560 オプションは次のとおりです。 2561 .LP 2562 .TS 2563 .if \n+(b.=1 .nr d. \n(.c-\n(c.-1 2564 .de 35 2565 .ps \n(.s 2566 .vs \n(.vu 2567 .in \n(.iu 2568 .if \n(.u .fi 2569 .if \n(.j .ad 2570 .if \n(.j=0 .na 2571 .. 2572 .nf 2573 .nr #~ 0 2574 .if n .nr #~ 0.6n 2575 .ds #d .d 2576 .if \(ts\n(.z\(ts\(ts .ds #d nl 2577 .fc 2578 .nr 33 \n(.s 2579 .rm 80 81 82 2580 .nr 34 \n(.lu 2581 .eo 2582 .am 80 2583 .br 2584 .di a+ 2585 .35 2586 .ft \n(.f 2587 .ll \n(34u*1u/4u 2588 .if \n(.l<\n(80 .ll \n(80u 2589 .in 0 2590 \-\f21.1\fP 2591 .br 2592 \-author 2593 .br 2594 \-\f2bootclasspath\fP 2595 .br 2596 \-bottom 2597 .br 2598 \-\f2breakiterator\fP 2599 .br 2600 \-charset 2601 .br 2602 \-\f2classpath\fP 2603 .br 2604 \-d 2605 .br 2606 \-docencoding 2607 .br 2608 \-docfilessubdirs 2609 .br 2610 \-\f2doclet\fP 2611 .br 2612 \-\f2docletpath\fP 2613 .br 2614 \-doctitle 2615 .br 2616 \-\f2encoding\fP 2617 .br 2618 \-\f2exclude\fP 2619 .br 2620 \-excludedocfilessubdir 2621 .br 2622 \-\f2extdirs\fP 2623 .br 2624 \-footer 2625 .br 2626 \-group 2627 .br 2628 .br 2629 .di 2630 .nr a| \n(dn 2631 .nr a- \n(dl 2632 .. 2633 .ec \ 2634 .eo 2635 .am 81 2636 .br 2637 .di b+ 2638 .35 2639 .ft \n(.f 2640 .ll \n(34u*1u/4u 2641 .if \n(.l<\n(81 .ll \n(81u 2642 .in 0 2643 \-header 2644 .br 2645 \-\f2help\fP 2646 .br 2647 \-helpfile 2648 .br 2649 \-\f2J\fP 2650 .br 2651 \-keywords 2652 .br 2653 \-link 2654 .br 2655 \-linkoffline 2656 .br 2657 \-linksource 2658 .br 2659 \-\f2locale\fP 2660 .br 2661 \-nocomment 2662 .br 2663 \-nodeprecated 2664 .br 2665 \-nodeprecatedlist 2666 .br 2667 \-nohelp 2668 .br 2669 \-noindex 2670 .br 2671 \-nonavbar 2672 .br 2673 \-noqualifier 2674 .br 2675 \-nosince 2676 .br 2677 \-notimestamp 2678 .br 2679 \-notree 2680 .br 2681 \-\f2overview\fP 2682 .br 2683 \-\f2package\fP 2684 .br 2685 .br 2686 .di 2687 .nr b| \n(dn 2688 .nr b- \n(dl 2689 .. 2690 .ec \ 2691 .eo 2692 .am 82 2693 .br 2694 .di c+ 2695 .35 2696 .ft \n(.f 2697 .ll \n(34u*1u/4u 2698 .if \n(.l<\n(82 .ll \n(82u 2699 .in 0 2700 \-\f2private\fP 2701 .br 2702 \-\f2protected\fP 2703 .br 2704 \-\f2public\fP 2705 .br 2706 \-\f2quiet\fP 2707 .br 2708 \-serialwarn 2709 .br 2710 \-\f2source\fP 2711 .br 2712 \-\f2sourcepath\fP 2713 .br 2714 \-sourcetab 2715 .br 2716 \-splitindex 2717 .br 2718 \-stylesheetfile 2719 .br 2720 \-\f2subpackages\fP 2721 .br 2722 \-tag 2723 .br 2724 \-taglet 2725 .br 2726 \-tagletpath 2727 .br 2728 \-top 2729 .br 2730 \-title 2731 .br 2732 \-use 2733 .br 2734 \-\f2verbose\fP 2735 .br 2736 \-version 2737 .br 2738 \-windowtitle 2739 .br 2740 .br 2741 .di 2742 .nr c| \n(dn 2743 .nr c- \n(dl 2744 .. 2745 .ec \ 2746 .35 2747 .nf 2748 .ll \n(34u 2749 .nr 80 0 2750 .80 2751 .rm 80 2752 .nr 38 \n(a- 2753 .if \n(80<\n(38 .nr 80 \n(38 2754 .nr 81 0 2755 .81 2756 .rm 81 2757 .nr 38 \n(b- 2758 .if \n(81<\n(38 .nr 81 \n(38 2759 .nr 82 0 2760 .82 2761 .rm 82 2762 .nr 38 \n(c- 2763 .if \n(82<\n(38 .nr 82 \n(38 2764 .35 2765 .nf 2766 .ll \n(34u 2767 .nr 38 1n 2768 .nr 79 0 2769 .nr 40 \n(79+(0*\n(38) 2770 .nr 80 +\n(40 2771 .nr 41 \n(80+(3*\n(38) 2772 .nr 81 +\n(41 2773 .nr 42 \n(81+(3*\n(38) 2774 .nr 82 +\n(42 2775 .nr TW \n(82 2776 .if t .if \n(TW>\n(.li .tm Table at line 1993 file Input is too wide - \n(TW units 2777 .fc 2778 .nr #T 0-1 2779 .nr #a 0-1 2780 .eo 2781 .de T# 2782 .ds #d .d 2783 .if \(ts\n(.z\(ts\(ts .ds #d nl 2784 .mk ## 2785 .nr ## -1v 2786 .ls 1 2787 .ls 2788 .. 2789 .ec 2790 .ne \n(a|u+\n(.Vu 2791 .ne \n(b|u+\n(.Vu 2792 .ne \n(c|u+\n(.Vu 2793 .if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v) 2794 .if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v) 2795 .if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v) 2796 .ta \n(80u \n(81u \n(82u 2797 .nr 31 \n(.f 2798 .nr 35 1m 2799 \&\h'|\n(40u'\h'|\n(41u'\h'|\n(42u' 2800 .mk ## 2801 .nr 31 \n(## 2802 .sp |\n(##u-1v 2803 .nr 37 \n(40u 2804 .in +\n(37u 2805 .a+ 2806 .in -\n(37u 2807 .mk 32 2808 .if \n(32>\n(31 .nr 31 \n(32 2809 .sp |\n(##u-1v 2810 .nr 37 \n(41u 2811 .in +\n(37u 2812 .b+ 2813 .in -\n(37u 2814 .mk 32 2815 .if \n(32>\n(31 .nr 31 \n(32 2816 .sp |\n(##u-1v 2817 .nr 37 \n(42u 2818 .in +\n(37u 2819 .c+ 2820 .in -\n(37u 2821 .mk 32 2822 .if \n(32>\n(31 .nr 31 \n(32 2823 .sp |\n(31u 2824 .fc 2825 .nr T. 1 2826 .T# 1 2827 .35 2828 .rm a+ 2829 .rm b+ 2830 .rm c+ 2831 .TE 2832 .if \n-(b.=0 .nr c. \n(.c-\n(d.-127 2833 .LP 2834 \f2イタリック\fP で示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、イタリックでないオプションを提供します。 2835 .SS 2836 Javadoc オプション 2837 .RS 3 2838 .TP 3 2839 \-overview \ path/filename 2840 Javadoc に対して、\f2path/filename\fP で指定された「ソース」ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ (\f2overview\-summary.html\fP) に配置するように指定します。 \f2path/filename\fP は、カレントディレクトリからの相対パスです。 2841 .LP 2842 \f2filename\fPで任意の名前を使用し、\f2path\fP で任意の配置先を選択することも可能ですが、通常は \f2overview.html\fP という名前を付け、ソースツリー内の最上位パッケージディレクトリを含むディレクトリ内に配置します。この場所に配置すると、パッケージをドキュメント化するときに \f2path\fP を指定する必要がなくなります。なぜなら、 \f2\-sourcepath\fP によってこのファイルが指し示されるからです。たとえば、 \f2java.lang\fP パッケージのソースツリーが \f2/src/classes/java/lang/\fP の場合、概要ファイルを \f2/src/classes/overview.html\fP に配置できます。「使用例」を参照してください。 2843 .LP 2844 \f2path/filename\fP で指定するファイルについては、「概要コメントファイル」を参照してください。 2845 .LP 2846 概要ページが作成されるのは、Javadoc に複数のパッケージ名を渡した場合だけです。詳細は、「HTML フレーム」を参照してください。 2847 .LP 2848 概要ページのタイトルは、\f2\-doctitle\fP によって設定されます。 2849 .LP 2850 .TP 3 2851 \-public 2852 public クラスおよびメンバーだけを表示します。 2853 .LP 2854 .TP 3 2855 \-protected 2856 protected および public のクラスとメンバーだけを表示します。これがデフォルトです。 2857 .LP 2858 .TP 3 2859 \-package 2860 package、protected、および public のクラスとメンバーだけを表示します。 2861 .LP 2862 .TP 3 2863 \-private 2864 すべてのクラスとメンバーを表示します。 2865 .LP 2866 .TP 3 2867 \-help 2868 オンラインヘルプを表示します。Javadoc とドックレットのコマンド行オプションが一覧表示されます。 2869 .LP 2870 .TP 3 2871 \-doclet\ class 2872 ドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。完全指定の名前を指定してください。このドックレットにより、出力の内容と形式が定義されます。\f4\-doclet\fP オプションが使われていない場合、Javadoc は、標準ドックレットを使ってデフォルトの HTML 形式を生成します。このクラスには \f2start(Root)\fP が含まれている必要があります。この起動クラスへのパスは \f2\-docletpath\fP オプションによって定義されます。 2873 .LP 2874 たとえば、MIF ドックレットを呼び出すには、次のように指定します。 2875 .nf 2876 \f3 2877 .fl 2878 \-doclet com.sun.tools.doclets.mif.MIFDoclet 2879 .fl 2880 \fP 2881 .fi 2882 .LP 2883 特定のドックレットを実行した完全な例については、 2884 .na 2885 \f2MIF Doclet のドキュメント\fP @ 2886 .fi 2887 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.htmlを参照してください。 2888 .LP 2889 .TP 3 2890 \-docletpath\ classpathlist 2891 \f2\-doclet\fP オプションで指定されたドックレット開始クラスファイル、 およびそのクラスが依存するすべての JAR ファイルへのパスを指定します。開始クラスファイルが jar ファイル内にある場合、以下の例のように jar ファイルのパスが指定されます。絶対パスまたは現在のディレクトリからの相対パスを指定できます。 \f2classpathlist\fP には、複数のパスまたは JAR ファイルを含めることができます。 その場合、各パスまたは JAR ファイルを、Solaris の場合にはコロン (:)、Windows の場合にはセミコロン (;) で区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。 2892 .LP 2893 jar ファイルへのパスの例には、ドックレット開始クラスファイルが含まれています。jar ファイル名が含まれている点に注目してください。 2894 .nf 2895 \f3 2896 .fl 2897 \-docletpath /home/user/mifdoclet/lib/mifdoclet.jar 2898 .fl 2899 \fP 2900 .fi 2901 ドックレット開始クラスファイルのパスの例。クラスファイル名が省略されている点に注目してください。 2902 .nf 2903 \f3 2904 .fl 2905 \-docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/ 2906 .fl 2907 \fP 2908 .fi 2909 特定のドックレットを実行した完全な例については、 2910 .na 2911 \f2MIF Doclet のドキュメント\fP @ 2912 .fi 2913 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.htmlを参照してください。 2914 .LP 2915 .TP 3 2916 \-1.1 2917 \f2この機能は Javadoc 1.4 から削除されました。代替機能はありません。このオプションは、Javadoc 1.1 によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした。入れ子のクラスはサポートされていません。このオプションが必要な場合は、Javadoc 1.2 または 1.3 を使用してください。\fP 2918 .LP 2919 .TP 3 2920 \-source release 2921 受け付けるソースコードのバージョンを指定します。\f2release\fP には次の値を指定できます。 2922 .RS 3 2923 .TP 2 2924 o 2925 \f31.5\fP \- javadoc は、JDK 1.5 で導入された総称などの言語機能を含むコードを受け付けます。\f3\-source\fP フラグが使用されなかった場合のコンパイラのデフォルト動作は、1.5 のものになります。 2926 .TP 2 2927 o 2928 \f31.4\fP Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。 2929 .TP 2 2930 o 2931 \f31.3\fP Javadoc は、JDK 1.3 以降に導入されたアサーション、総称、または他の言語機能をサポートしません。 2932 .RE 2933 .LP 2934 javac でコードをコンパイルするときに使用した値に対応する \f2release\fP の値を使用します。 2935 .LP 2936 .TP 3 2937 \-sourcepath\ sourcepathlist 2938 パッケージ名または \-subpackages を javadoc コマンドに渡すときは、ソースファイル (.\f2.java\fP) を見つけるための \f2検索パス\fP を指定 \f2します\fP 。\f2sourcepathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使って、ドキュメント化されるソースファイルの位置だけでなく、それ自体はドキュメント化されないがドキュメント化されるソースファイルから継承されたコメントを持つソースファイルの位置も確認できます。 2939 .LP 2940 \f2\-sourcepath\fP オプションを使用できるのは、javadoc コマンドにパッケージ名を渡す場合だけです。このパスからは、javadoc コマンドに渡された \f2.java\fP ファイルは \f2検索\fP されません。 \f2.java\fP ファイルを検索するには、そのファイルのあるディレクトリに cd によって移動するか、または各ファイルの先頭にパスを含めます (「1 つ以上のクラスのドキュメント化」を参照)。 \f2\-sourcepath\fP が省略された場合、Javadoc は、クラスパスを使ってソースファイルを検索します (\-classpath を参照)。したがって、デフォルトの \-sourcepath は、クラスパスの値です。\-classpath も省略してパッケージ名を Javadoc に渡すと、Javadoc は現在のディレクトリおよびそのサブディレクトリからソースファイルを検索します。 2941 .LP 2942 \f2sourcepathlist\fP には、ドキュメント化するパッケージ名のソースツリーのルートディレクトリを設定します。たとえば、 \f2com.mypackage\fP という名前のパッケージをドキュメント化する場合に、そのソースファイルが次の場所にあるとします。 2943 .nf 2944 \f3 2945 .fl 2946 /home/user/src/com/mypackage/*.java 2947 .fl 2948 \fP 2949 .fi 2950 このとき次のように、 \f2sourcepath\fP を、com/mypackage を含むディレクトリである \f2/home/user/src\fP に指定したあと、 パッケージ名 \f2com.mypackage\fP を指定します。 2951 .nf 2952 \f3 2953 .fl 2954 % \fP\f3javadoc \-sourcepath /home/user/src/ com.mypackage\fP 2955 .fl 2956 .fi 2957 この方法は、ソースパスの値とパッケージ名を連結して、ドットを (円記号) 「\\」に変えると、パッケージのフルパス \f2/home/user/src/com/mypackage になることを理解すると簡単です\fP。 2958 .LP 2959 2 つのソースパスを設定するには、次のようにします。 2960 .nf 2961 \f3 2962 .fl 2963 % \fP\f3javadoc \-sourcepath /home/user1/src:/home/user2/src com.mypackage\fP 2964 .fl 2965 .fi 2966 .LP 2967 .TP 3 2968 \-classpath\ classpathlist 2969 javadoc が参照クラス (\f2.class\fP ファイル) の検索を行うときに使用するパスを指定します。参照クラスとは、ドキュメント化されるクラスと、それらのクラスから参照されるすべてのクラスを指します。\f2classpathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。classpathlist を指定するときは、 2970 .na 2971 \f2クラスパス\fP @ 2972 .fi 2973 http://java.sun.com/javase/6/docs/technotes/tools/index.html#generalのドキュメントにある指示 \f2に従ってください\fP。 2974 .LP 2975 \f2\-sourcepath\fP が省略されると、Javadoc ツールはクラスファイルを検索するときだけでなく、ソースファイルを検索するときにも \f2\-classpath\fP を使用します (下位互換性のため)。したがって、ソースファイルとクラスファイルを別々のパスから検索する必要がある場合は、 \f2\-sourcepath\fP と \f2\-classpath の両方を使います\fP.。 2976 .LP 2977 たとえば、 \f2com.mypackage\fP をドキュメント化する場合に、そのソースファイルがディレクトリ \f2/home/user/src/com/mypackage\fP 内に格納されており、このパッケージが \f2/home/user/lib\fP 内のライブラリに依存しているとします。このとき次のように指定します。 2978 .nf 2979 \f3 2980 .fl 2981 % \fP\f3javadoc \-classpath /home/user/lib \-sourcepath /home/user/src com.mypackage\fP 2982 .fl 2983 .fi 2984 \f2\-classpath\fP が指定されなかった場合、Javadoc ツールはほかのツールと同じく、CLASSPATH 環境変数が設定されていればその値を使用します。どちらも設定されていない場合、Javadoc ツールは現在のディレクトリからクラスを検索します。 2985 .LP 2986 Javadoc ツールが \f2\-classpath\fP を使用してユーザークラスを検索する方法について、拡張クラスやブートストラップクラスと関連付けて説明している情報を入手するには、 2987 .na 2988 \f2「クラスの検索方法」\fP @ 2989 .fi 2990 http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.htmlを参照してください。 2991 .LP 2992 便宜上、 \f2*\fP のベース名を含むクラスパス要素は、 \f2.jar\fP または \f2.JAR\fP を拡張子に持つディレクトリ内のすべてのファイルのリストを指定するのと同等とみなされます (java プログラムはこの 2 つの呼び出しを区別できない)。 2993 .br 2994 .br 2995 たとえば、ディレクトリ \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 プログラムが展開されていないワイルドカードを認識することはありません。 2996 .LP 2997 .TP 3 2998 \-subpackages\ \ package1:package2:... 2999 ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 \f2package\fP 引数は、任意の最上位サブパッケージ ( \f2java\fP など) または完全修飾パッケージ ( \f2javax.swing\fP など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、\f2\-sourcepath\fP を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。 3000 .LP 3001 たとえば、 3002 .nf 3003 \f3 3004 .fl 3005 % \fP\f3javadoc \-d docs \-sourcepath /home/user/src \-subpackages java:javax.swing\fP 3006 .fl 3007 .fi 3008 このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。 3009 .LP 3010 \f2\-subpackages\fP と \f2\-exclude\fP を組み合わせて使用すると、特定のパッケージを除外できます。 3011 .LP 3012 .TP 3 3013 \-exclude\ \ packagename1:packagename2:... 3014 指定されたパッケージとそのサブパッケージを \f2\-subpackages\fP によって作成されたリストから無条件に除外します。 過去の \f2\-subpackages\fP オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。 次に例を示します。 3015 .nf 3016 \f3 3017 .fl 3018 % \fP\f3javadoc \-sourcepath /home/user/src \-subpackages java \-exclude java.net:java.lang\fP 3019 .fl 3020 .fi 3021 この場合、 \f2java.io\fP、 \f2java.util\fP、 \f2java.math\fP などが含められ、 \f2java.net\fP と \f2java.lang\fP をルートに持つパッケージが除外されます。この場合、 \f2java.lang\fP のサブパッケージである \f2java.lang.ref\fP も除外される点に注意してください。 3022 .LP 3023 .TP 3 3024 \-bootclasspath\ classpathlist 3025 ブートクラスが存在するパスを指定します。ブートクラスとは、通常、Java プラットフォームのコアクラスのことです。ブートクラスパスは、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、 3026 .na 3027 \f2「クラスの検索方法」\fP @ 3028 .fi 3029 http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfilesを参照してください。コロン (:) を、 \f2classpathlist\fP 内のディレクトリ間の区切り文字として使用します。 3030 .LP 3031 .TP 3 3032 \-extdirs\ dirlist 3033 拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java 拡張機能機構を使うすべてのクラスです。extdirs は、Javadoc ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。詳細は、前述の \f2\-classpath\fP を参照してください。コロン (:) を、 \f2dirlist\fP 内のディレクトリ間の区切り文字として使用します。 3034 .LP 3035 .TP 3 3036 \-verbose 3037 javadoc の実行中に詳細なメッセージを表示します。verbose オプションを指定しないと、ソースファイルのロード時、ドキュメントの生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時にメッセージが表示されます。verbose オプションを指定すると、各 Java ソースファイルの解析に要した時間 (ミリ秒単位) など、追加のメッセージが表示されます。 3038 .LP 3039 .TP 3 3040 \-quiet 3041 エラーメッセージまたは警告メッセージ以外のメッセージを抑制し、警告とエラーだけが表示されるようにして、これらを特定しやすくします。バージョン文字列も抑制します。 3042 .LP 3043 .TP 3 3044 \-breakiterator\ 3045 英語の最初の文の末尾を決定する際に、英語用のロケール固有のアルゴリズムではなく、 3046 .na 3047 \f2java.text.BreakIterator\fP @ 3048 .fi 3049 http://java.sun.com/javase/6/docs/api/java/text/BreakIterator.html の国際化された文境界を使用します (ほかのすべてのロケールではすでに \f2BreakIterator\fP が使用されている)。\f2「最初の文」\fPとは、パッケージ、クラス、またはメンバーの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバーの要約にコピーされ、アルファベット順のインデックスにコピーされます。 3050 .LP 3051 JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、 \f2\-breakiterator\fP オプションは、1.2 以降では英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。 3052 .RS 3 3053 .TP 2 3054 o 3055 英文のデフォルトの文区切りアルゴリズム \- 空白または HTML ブロックタグ ( \f2<P>\fP など) が続くピリオドで停止する 3056 .TP 2 3057 o 3058 breakiterator 文区切りアルゴリズム \- 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは「The serial no. is valid」など、ほとんどの省略表記が処理されますが、「Mr. Smith」などは処理されません。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する 3059 .RE 3060 .LP 3061 注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\\\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。この件で皆様に余分の手間をおかけし、混乱を招いたことをお詫びいたします。 3062 .TP 3 3063 \-locale\ language_country_variant 3064 .LP 3065 \f3重要\fP \- \f2\-locale\fP オプションは、\f2標準ドックレットが提供するすべてのオプション\fP、またはその他の任意のドックレットの提供するすべてのオプションより前 (左側) に指定する必要があります。そうしないと、ナビゲーションバーが英語で表示されます。このコマンド行オプションだけは、指定する順序に依存します。 3066 .LP 3067 Javadoc がドキュメントを生成するときに使うロケールを指定します。この引数は次のような、java.util.Locale のドキュメンテーションで説明されているロケールの名前です。 \f2en_US\fP (英語、米国) または \f2en_US_WIN\fP (Windows で使用される英語)。 3068 .LP 3069 ロケールを指定すると、指定したロケールのリソースファイルが Javadoc によって選択されて、メッセージ (ナビゲーションバー、リストと表の見出し、ヘルプファイルの目次、stylesheet.css のコメントなどの文字列) のために使われます。また、アルファベット順にソートされるリストのソート順、および最初の文の末尾を判別するための文の区切り文字も、指定したロケールによって決まります。ただし、このオプションは、ドキュメント化されるクラスのソースファイル内で指定されているドキュメンテーションコメントのテキストのロケールを決定するものではありません。 3070 .LP 3071 .TP 3 3072 \-encoding\ name 3073 ソースファイルのエンコーディングの名前 ( \f2EUCJIS/SJIS\fP など) を指定します。 このオプションが指定されていない場合は、プラットフォームのデフォルトコンバータが使われます。 3074 .LP 3075 \-docencoding および \-charset も参照してください。 3076 .LP 3077 .TP 3 3078 \-Jflag 3079 javadoc を実行する実行時システム java に、\f2flag\fP を直接渡します。 \f2J\fP と \f2flag\fP の間に空白を入れないように注意してください。たとえば、生成ドキュメントの処理用として32M バイトのメモリーをシステムで確保しておく必要がある場合には、java の \f2\-Xmx\fP オプションを次のように呼び出します。\f2\-Xms\fP は省略可能です。これは、メモリーの初期サイズを設定するだけのオプションで、メモリーの最低必要量がわかっている場合に便利です。 3080 .nf 3081 \f3 3082 .fl 3083 % \fP\f3javadoc \-J\-Xmx32m \-J\-Xms32m\fP \f3com.mypackage\fP 3084 .fl 3085 .fi 3086 使用している javadoc のバージョンを確認するには、次のように Java の\f2「\-version」\fPオプションを呼び出します。 3087 .nf 3088 \f3 3089 .fl 3090 % \fP\f3javadoc \-J\-version\fP 3091 .fl 3092 java version "1.2" 3093 .fl 3094 Classic VM (build JDK\-1.2\-V, green threads, sunwjit) 3095 .fl 3096 .fi 3097 出力ストリームには標準ドックレットのバージョン番号が含まれます。 3098 .RE 3099 .SS 3100 標準ドックレットが提供するオプション 3101 .RS 3 3102 .TP 3 3103 \-d\ directory 3104 生成された HTML ファイルを保存する生成先ディレクトリを指定します(「d」は「生成先 (destination)」の意味)。このオプションを省略すると、生成されたファイルは現在のディレクトリに保存されます。値 \f2directory\fP には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。バージョン 1.4 では、javadoc を実行すると生成先ディレクトリが自動的に作成されます。 3105 .LP 3106 たとえば次の場合、パッケージ \f2com.mypackage\fP のドキュメントが生成され、その結果が \f2/home/user/doc/\fP ディレクトリに保存されます。 3107 .nf 3108 \f3 3109 .fl 3110 % \fP\f3javadoc \-d /home/user/doc com.mypackage\fP 3111 .fl 3112 .fi 3113 .LP 3114 .TP 3 3115 \-use 3116 ドキュメント化されるクラスおよびパッケージごとに 1 つの「使用」ページを組み込みます。このページには、その特定のクラスまたはパッケージの API を使っているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラス C を例にとると、クラス C を使っているものとしては、C のサブクラス、C として宣言されているフィールド、C を返すメソッド、および、型 C のパラメータを持つメソッドとコンストラクタがあります。 3117 .LP 3118 たとえば、String の [使用] ページに何が表示されるかを見てみましょう。java.awt.Font クラスの \f2getName()\fP メソッドは、 \f2String\fP 型の値を \f2返します\fP。したがって、 \f2getName()\fP は \f2String\fP を使用しているので、String の [使用] ページに \f2このメソッドが表示されます\fP。 3119 .LP 3120 ただし、ドキュメント化されるのは API の使用だけであって、実装はドキュメント化されません。あるメソッドが、その実装の中で \f2String\fP を使っていても、引数として文字列をとったり、文字列を返したりしない場合は、 \f2String\fP の「使用」とはみなされません。 3121 .LP 3122 生成された [使用] ページにアクセスするには、目的のクラスまたはパッケージに移動し、ナビゲーションバーの [使用] リンクをクリックします。 3123 .TP 3 3124 \-version 3125 生成ドキュメントに、@version のテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用している Javadoc ツールのバージョンを確認するには \f2\-J\-version\fP オプションを使用します。 3126 .LP 3127 .TP 3 3128 \-author 3129 生成ドキュメントに、@author のテキストを組み込みます。 3130 .LP 3131 .TP 3 3132 \-splitindex 3133 索引ファイルをアルファベットごとに複数のファイルに分割し、文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる索引エントリ用に 1 つのファイルを作成します。 3134 .LP 3135 .TP 3 3136 \-windowtitle\ title 3137 HTML の <title> タグに配置するタイトルを指定します。指定したタイトルは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク (お気に入り) に表示されます。このタイトルには HTML タグを含めないでください。タイトルに HTML タグが含まれていると、ブラウザがタグを正しく解釈できません。\f2title\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。\-windowtitle が省略されている場合、Javadoc ツールは、このオプションの代わりに \-doctitle の値を使います。 3138 .nf 3139 \f3 3140 .fl 3141 % \fP\f3javadoc \-windowtitle "Java SE Platform" com.mypackage\fP 3142 .fl 3143 .fi 3144 .TP 3 3145 \-doctitle\ title 3146 概要ファイルの最上部の近くに配置するタイトルを指定します。タイトルは中央揃えになり、レベル 1 の見出しとして、上部ナビゲーションバーのすぐ下に置かれます。\f2title\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2title\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。 3147 .nf 3148 \f3 3149 .fl 3150 % \fP\f3javadoc \-doctitle "Java(TM)" com.mypackage\fP 3151 .fl 3152 .fi 3153 .TP 3 3154 \-title\ title 3155 \f3このオプションはもう存在していません。\fPこのオプションは Javadoc 1.2 のベータ版にしか存在していませんでした。このオプションの名前は \f2\-doctitle\fP に変更されました。名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。 3156 .LP 3157 .TP 3 3158 \-header\ header 3159 各出力ファイルの上端に配置するヘッダーテキストを指定します。ヘッダーは、上部ナビゲーションバーの右側に配置されます。\f2header\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2header\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。 3160 .nf 3161 \f3 3162 .fl 3163 % \fP\f3javadoc \-header "<b>Java 2 Platform </b><br>v1.4" com.mypackage\fP 3164 .fl 3165 .fi 3166 .LP 3167 .TP 3 3168 \-footer\ footer 3169 各出力ファイルの下端に配置するフッターテキストを指定します。フッターは、下部ナビゲーションバーの右側に配置されます。\f2footer\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。\f2footer\fP の中で引用符を使う場合は、引用符をエスケープする必要があります。 3170 .LP 3171 .TP 3 3172 \-top 3173 各出力ファイルの上端に配置するテキストを指定します。 3174 .LP 3175 .TP 3 3176 \-bottom\ text 3177 各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーションバーより下の、ページの最下部に配置されます。 \f2text\fP には、HTML タグと空白を含めることができますが、これらを含める場合は、全体を引用符で囲まなければなりません。引用符を \f2text\fP 内で使用する場合、引用符をエスケープしなければならない可能性があります。 3178 .LP 3179 .TP 3 3180 \-link\ extdocURL 3181 javadoc により生成された既存の外部参照クラスのドキュメンテーションへのリンクを作成します。引数を 1 つとります。 3182 .LP 3183 .RS 3 3184 .TP 2 3185 o 3186 \f4extdocURL\fP は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。あとで例を示します。このディレクトリ内にパッケージリストファイルが存在していなければなりません。 存在しない場合は、\f2\-linkoffline\fP を使用します。Javadoc ツールは、 \f2package\-list\fP ファイルからパッケージ名を読み取ったあと、その URL でそれらのパッケージにリンクします。Javadoc ツールの実行時に、\f2extdocURL\fP の値がそのまま、作成された \f2<A HREF>\fP リンク内にコピーされます。したがって、\f2extdocURL\fP はファイルへの URL ではなく「ディレクトリへの URL」でなければなりません。 3187 .LP 3188 \f2extdocURL\fP への絶対リンクを使用すると、ユーザーのドキュメントを任意の Web サイト上のドキュメントにリンクできます。相対位置へリンクするだけでよい場合は相対リンクを使用できます。相対リンクの場合、ユーザーが渡す値は、( \f2\-d\fP で指定された) 生成先ディレクトリから、リンク先となるパッケージを含むディレクトリへの相対パスにすべきです。 3189 .LP 3190 通常、絶対リンクを指定する場合は、 \f2http:\fP リンクを使用します。Web サーバーを持たないファイルシステムにリンクする場合は、 \f2file: リンクを使用できます。\fP ただし、この方法は、すべてのユーザーが生成された同じファイルシステムを共有するドキュメントにアクセスする必要がある場合以外は使用しないでください。 3191 .LP 3192 すべての場合、すべてのオペレーティングシステムで、絶対 URL と相対 URL、「http:」ベースと「file:」ベースにかかわらず、スラッシュを区切り文字として使用します ( 3193 .na 3194 \f2URL Memo\fP @ 3195 .fi 3196 http://www.ietf.org/rfc/rfc1738.txt で指定)。 3197 .RS 3 3198 .TP 3 3199 http: ベースの絶対リンク: 3200 \f2\-link http://<host>/<directory>/<directory>/.../<name>\fP 3201 .TP 3 3202 file: ベースの絶対リンク: 3203 \f2\-link file://<host>/<directory>/<directory>/.../<name>\fP 3204 .TP 3 3205 相対リンク: 3206 \f2\-link <directory>/<directory>/.../<name>\fP 3207 .RE 3208 .RE 3209 .LP 3210 javadoc の 1 回の実行で複数の \f2\-link\fP オプションを指定すれば、複数のドキュメントへのリンクを作成できます。 \f3\-linkoffline または \-link の選択\fP 3211 .br 3212 \f2\-link\fPを使用する場合: 3213 .RS 3 3214 .TP 2 3215 o 3216 外部 API ドキュメントへの相対パスを使用する場合 3217 .TP 2 3218 o 3219 外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されている場合) 3220 .RE 3221 \f2\-linkoffline\fP を使用する場合: 3222 .RS 3 3223 .TP 2 3224 o 3225 外部 API ドキュメントへの絶対 URL を使用する場合 (プログラムがその URL に接続し、読み取りを行うことがシェルによって許可されていない場合)このような状況は、リンク先のドキュメントがファイアウォールの向こう側にある場合に発生します。 3226 .RE 3227 .LP 3228 \f3外部ドキュメントへの絶対リンクの使用例\fP \- \f2java.lang\fP、 \f2java.io\fP 、その他の Java プラットフォームパッケージ ( 3229 .na 3230 \f2http://download.oracle.com/javase/7/docs/api/\fP @ 3231 .fi 3232 http://download.oracle.com/javase/7/docs/api/ 内) にリンクしたい場合があります。次のコマンドは、Java SE プラットフォームパッケージへのリンクを含んだ、パッケージ \f2com.mypackage\fP のドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内の \f2Object\fP クラスへのリンクが含まれています。なお、 \f2\-sourcepath\fP や \f2\-d\fP など、その他のオプションは示していません。 3233 .nf 3234 \f3 3235 .fl 3236 % \fP\f3javadoc \-link http://download.oracle.com/javase/7/docs/api/ com.mypackage\fP 3237 .fl 3238 .fi 3239 \f3外部ドキュメントへの相対リンクの使用例\fP \- 2 つのパッケージがあり、そのドキュメントが Javadoc ツールを複数回実行した結果生成されたものであるとします。さらに、これらのドキュメントが相対パスで分割されているとします。この例の場合、パッケージは、API である \f2com.apipackage\fP と、SPI (サービスプロバイダインタフェース) である \f2com.spipackage\fP です。ドキュメントの格納先は、 \f2docs/api/com/apipackage\fP と \f2docs/spi/com/spipackage\fP です。API パッケージのドキュメントはすでに生成済みで、 \f2docs\fP がカレントディレクトリになっていると仮定すると、API ドキュメントへのリンクを含む SPI パッケージをドキュメント化するには、次のコマンドを実行します。 3240 .nf 3241 \f3 3242 .fl 3243 % \fP\f3javadoc \-d ./spi \-link ../api com.spipackage\fP 3244 .fl 3245 .fi 3246 .LP 3247 \f2\-link\fP の引数は、生成先ディレクトリ (\f2docs/spi\fP) からの相対パスです。 3248 .LP 3249 \f3詳細\fP \- \f2\-link\fP オプションを使うと、「コードからは参照されていても、Javadoc の今回の実行ではドキュメント化されない」というクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらの HTML ページがある場所を調べ、その場所を \f2extdocURL\fP に指定する必要があります。これにより、たとえば、サードパーティーのドキュメントから \f2http://java.sun.com 上の java.*\fP のドキュメントへのリンクが \f2可能となります\fP。 3250 .LP 3251 今回の実行で Javadoc によって生成されるドキュメント内の API だけを対象に \f2リンクを作成する場合は、\fP \-link オプションを省略します。 \f2\-link\fP オプションが指定されていない場合、Javadoc ツールは、外部参照されたドキュメントへのリンクを作成しません。これは、そのドキュメントが存在するかどうか、および存在する場合はその場所を判別できないからです。 3252 .LP 3253 このオプションでは、生成ドキュメント内の複数の場所にリンクを作成できます。 3254 .LP 3255 もう 1 つの用途は、パッケージセット間でのクロスリンクです。一方のパッケージセットに対して javadoc を実行したあと、他方のパッケージセットに対して javadoc を再度実行することにより、両セット間で双方向のリンクを作成できます。 3256 .LP 3257 \f3クラスの参照方法\fP \- 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。それらのクラスは、 \f2import\fP 文、宣言のいずれの場所で参照されている必要があります。Here are examples of how the class \f2java.io.File\fP can be referenced: 3258 .RS 3 3259 .TP 2 3260 o 3261 すべての種類の \f2import\fP 文の場合: ワイルドカードによるインポート、名前による明示的なインポート、または \f2java.lang.* に対する自動的なインポート\fP。たとえば、次のようにすれば十分です。 3262 .br 3263 \f2import java.io.*;\fP 3264 .br 3265 1.3.x および 1.2.x では、名前による明示的なインポートだけです。ワイルドカードによるインポート文も、 \f2java.lang.* の自動インポートも使用できません\fP。 3266 .TP 2 3267 o 3268 宣言の場合: 3269 .br 3270 \f2void foo(File f) {}\fP 3271 .br 3272 この参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースの戻り値の型またはパラメータの型に置くか、 \f2implements\fP、 \f2extends\fP 、または \f2throws\fP 文に置きます。 3273 .RE 3274 .LP 3275 重要な結果として、 \f2\-link\fP オプションの使用時に、この制限のために誤って表示されないリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安全な方法は上で説明したとおり、当該のクラスをインポートすることです。 3276 .LP 3277 \f3パッケージリスト\fP \- \f2\-link\fP オプションが正しく機能するには、Javadoc ツールによって生成される \f2package\-list\fP という名前のファイルが、ユーザーが \f2\-link\fP に指定した URL に存在している必要があります。 \f2package\-list\fP ファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキストファイルです。前の例では、Javadoc ツールは、指定された URL で \f2package\-list\fP という名前のファイルを検索し、パッケージ名を読み込んだあと、その URL にあるそれらのパッケージへのリンクを作成しました。 3278 .LP 3279 たとえば、Java SE 6 API のパッケージリストは 3280 .na 3281 \f2http://download.oracle.com/javase/7/docs/api/package\-list\fP @ 3282 .fi 3283 http://download.oracle.com/javase/7/docs/api/package\-list にあり、次のような内容で始まっています。 3284 .nf 3285 \f3 3286 .fl 3287 java.applet 3288 .fl 3289 java.awt 3290 .fl 3291 java.awt.color 3292 .fl 3293 java.awt.datatransfer 3294 .fl 3295 java.awt.dnd 3296 .fl 3297 java.awt.event 3298 .fl 3299 java.awt.font 3300 .fl 3301 その他 3302 .fl 3303 \fP 3304 .fi 3305 .LP 3306 \f2\-link\fP オプションを指定せずに javadoc を実行した場合、外部参照クラスに属する名前を見つけると、javadoc はその名前をリンクを持たない形で出力します。一方、 \f2\-link\fP オプションが指定された場合、Javadoc ツールは、 \f2指定された\fP \f2extdocURL\fP の場所にある package\-list ファイル内で、そのパッケージ名を検索します。パッケージ名が見つかると、\f2extdocURL\fP が名前の前に付加されます。 3307 .LP 3308 すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定した URL に存在していなければなりません。Javadoc ツールは、指定された package\-list が存在するかどうかを調べるだけで、指定された URL に目的のページが存在するかどうかはチェックしません。 3309 .LP 3310 \f3複数のリンク\fP \- 複数の \f2\-link\fP オプションを指定すると、任意の数の外部生成ドキュメントへのリンクを作成できます。Javadoc 1.2 には、複数の \f2\-link\fP コマンドを指定できないというバグがあります。これは 1.2.2 で修正されました。 3311 .LP 3312 リンクする外部ドキュメントごとに、次のように別々のリンクオプションを指定します。 3313 .LP 3314 \ \ \f2% \fP\f4javadoc \-link\fP \f2extdocURL1\fP \f4\-link\fP \f2extdocURL2\fP \f2... \fP\f4\-link\fP \f2extdocURLn\fP \f4com.mypackage\fP 3315 .LP 3316 \f2extdocURL1\fP、\f2extdocURL2\fP、... \f2extdocURLn\fP は、それぞれ外部ドキュメントのルートを指し、各ルートには、 \f2package\-list\fP という名前のファイルが入っています。 3317 .LP 3318 \f3クロスリンク\fP \- まだ生成されていない 2 つ以上のドキュメントをクロスリンクする場合は、「ブートストラップ」が必要になります。つまり、どのドキュメントについても \f2package\-list\fP が存在していない場合は、最初のドキュメントに対して Javadoc ツールを実行する時点で、2 番目のドキュメントの \f2package\-list\fP はまだ存在していません。したがって、外部リンクを作成するには、2 番目のドキュメントを生成したあとで、最初のドキュメントを生成し直す必要があります。 3319 .LP 3320 この場合、最初のドキュメント生成の目的は、 \f2package\-list\fP を作成することです。パッケージ名をすべて把握している場合は、package\-list を手動で作成してもかまいません。次に、2 番目のドキュメントとその外部リンクを生成します。必要な外部の \f2package\-list\fP ファイルが存在しない場合は、Javadoc ツールから警告が出力されます。 3321 .LP 3322 .TP 3 3323 \-linkoffline\ extdocURL\ packagelistLoc 3324 このオプションは \f2\-link\fP のバリエーションの 1 つです。どちらも、外部参照クラスの javadoc 生成ドキュメントへのリンクを作成します。Javadoc \f2ツール自体が\fP オフラインになっているとき (Web 接続を使ってドキュメントにアクセスできないとき)、Web 上のドキュメントにリンクするには、\-linkoffline オプションを使用します。 3325 .LP 3326 厳密には、 \f2外部\fP ドキュメントの \f2package\-list\fP ファイルにアクセスできないとき、またはこのファイルが \f2extdocURL\fP で指定された場所とは異なる場所 (通常、\f2packageListLoc\fP で指定可能なローカルな場所) に存在するとき、\-linkoffline を使用します。したがって、WWW 経由でしか \f2extdocURL\fP にアクセスできない場合、 \f2\-linkoffline\fP を指定することにより、ドキュメントの生成時に Javadoc ツールが Web に接続できなければならないという制約がなくなります。 3327 .LP 3328 さらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。 3329 .LP 3330 \f2\-linkoffline\fP オプションは引数を 2 つ取ります。1 つは、 \f2<a href>\fP リンクに組み込まれる文字列を表す引数、もう 1 つは \f2package\-list\fP の検索場所を示す引数です。 3331 .RS 3 3332 .TP 2 3333 o 3334 \f4extdocURL\fP は、リンク先として指定する、javadoc によって生成された外部ドキュメントを含むディレクトリの絶対 URL または相対 URL です。相対リンクの場合、その値は、( \f2\-d\fP で指定された) 生成先ディレクトリからリンク先パッケージのルートへの相対パスにすべきです。詳細は、\-link オプションの \f2extdocURL\fP \f2を参照\fP してください。 3335 .TP 2 3336 o 3337 \f4packagelistLoc\fP は、外部ドキュメントの \f2package\-list\fP ファイルを含むディレクトリへのパスまたは URL です。これは、URL (http: または file:) でもファイルパスでもかまいませんし、絶対パスでも相対パスでもかまいません。相対パスの場合は、javadoc が実行されるカレントディレクトリからの相対パスとして指定します。ファイル名 \f2package\-list\fP は含めないでください。 3338 .RE 3339 .LP 3340 1 回の javadoc 実行で複数の \f2\-linkoffline\fP オプションを指定できます。1.2.2 より前は、複数のオプションを指定することはできませんでした。 3341 .LP 3342 \f3外部ドキュメントへの絶対リンクの使用例\fP \- http://download.oracle.com/javase/7/docs/api/ 内の \f2java.lang\fP、 \f2java.io\fP 、およびその他の Java SE プラットフォームパッケージ \f2にリンクしたくても、\fPWeb にアクセスできない場合を考えます。ブラウザで \f2、\fP 3343 .na 3344 \f2http://download.oracle.com/javase/7/docs/api/package\-list\fP @ 3345 .fi 3346 http://download.oracle.com/javase/7/docs/api/package\-list にある package\-list ファイルを開き、それをローカルディレクトリに保存し、第 2 引数 \f2packagelistLoc\fP でこのローカルコピーへのパスを指定します。この例では、パッケージリストファイルはカレントディレクトリ "\f2.\fP" に保存されています。次のコマンドは、Java SE プラットフォームパッケージへのリンクを含んだ、パッケージ \f2com.mypackage\fP のドキュメントを生成します。生成されたドキュメントには、たとえばクラスツリー内の \f2Object\fP クラスへのリンクが含まれています。なお、 \f2\-sourcepath\fP など、その他のオプションは示していません。 3347 .nf 3348 \f3 3349 .fl 3350 % \fP\f3javadoc \-linkoffline http://download.oracle.com/javase/7/docs/api/ . com.mypackage\fP 3351 .fl 3352 .fi 3353 .LP 3354 \f3外部ドキュメントへの相対リンクの使用例\fP \- \f2\-linkoffline\fP で相対パスを使用することは、あまりありません。理由は単純で、通常は \f2\-link\fP で十分だからです。 \f2\-linkoffline\fP を使用する際、 \f2package\-list\fP には通常ローカルのファイルを指定します。 相対リンクを使用する際も、リンク先のファイルには通常ローカルのファイルを指定します。したがって、 \f2\-linkoffline の 2 つの引数に別々のパスを指定する必要はありません\fP。2 つの引数が同一である場合は、 \f2\-link\fP を使用できます。 \f2\-link\fP の相対リンクの例を参照してください。 3355 .LP 3356 \f4package\-list\fP\f3 ファイルを手動で作成\fP \- \f2package\-list\fP ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルを自分で作成し、packagelistLoc \f2でそのパスを指定することができます。\fPcom.apipackage が最初に生成される時点で \f2com.spipackage\fP のパッケージリストが存在していなかったという、 \f2前出のケースが\fP 一例として挙げられます。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、Javadoc 1.0 または 1.1 で生成されたパッケージの \f2package\-list\fP ファイルを作成する必要がある場合にも、この方法が使えます。これらのバージョンでは、 \f2package\-list\fP ファイルは生成されていませんでした。同様に、2 つの企業が未公開の \f2package\-list\fP ファイルを共有すれば、クロスリンクを含むドキュメントを同時にリリースすることも可能となります。 3357 .LP 3358 \f3複数のドキュメントへのリンク\fP \- 参照先となる生成ドキュメントごとに \f2\-linkoffline\fP を 1 回ずつ含めることができます。わかりやすくするために、オプションごとに改行して示しています。 3359 .LP 3360 \f2% \fP\f4javadoc \-linkoffline\fP \f2extdocURL1\fP \f2packagelistLoc1\fP \f2\\\fP 3361 .br 3362 \f2\ \ \ \ \ \ \ \ \ \ \fP\f4\-linkoffline\fP \f2extdocURL2\fP \f2packagelistLoc2\fP \f2\\\fP 3363 .br 3364 \f2\ \ \ \ \ \ \ \ \ \ ...\fP 3365 .LP 3366 \f3ドキュメントの更新\fP \- 前述の \f2\-linkoffline\fP オプションのもうひとつの用途は、プロジェクトに大量のパッケージが含まれていて、すでにツリー全体に対して javadoc の実行が完了している場合に、次の実行では、少量の変更を手早く加えたあと、ソースツリーのごく一部に対してだけ javadoc を再実行する場合に便利です。これは、ドキュメンテーションコメントに対してだけ変更を加え、宣言は変更しない場合にのみ正しく処理されるので、ハッキングのようなものです。ソースコードの宣言を追加、削除、または変更した場合は、索引、パッケージツリー、継承されるメンバーのリスト、「使用」ページなどの場所で、リンクが壊れることがあります。 3367 .LP 3368 まず、この新しい小さな実行用として、新しい生成先ディレクトリ ( \f2update\fP と命名) を作成します。元の生成先ディレクトリの名前が \f2html\fP だったとします。もっとも単純な例では、 \f2html ディレクトリの親ディレクトリに移動 (cd) します\fP。 \f2\-linkoffline\fP の第 1 引数をカレントディレクトリ「.」に設定し、第 2 引数を、package\-list が含まれている \f2html\fP への相対パスに設定し、 \f2更新するパッケージのパッケージ名のみを\fP渡します。 3369 .nf 3370 \f3 3371 .fl 3372 % \fP\f3javadoc \-d update \-linkoffline . html com.mypackage\fP 3373 .fl 3374 .fi 3375 Javadoc ツリーの終了後、 \f2update/com/package\fP 内の生成されたクラスのページをコピーし (概要や索引は除く)、 \f2html/com/package 内の元のファイルに上書きします\fP。 3376 .LP 3377 .TP 3 3378 \-linksource\ 3379 各ソースファイル (行番号付き) の HTML バージョンを作成し、標準 HTML ドキュメントからソースファイルへのリンクを追加します。リンクは、ソースファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。デフォルトコンストラクタ、生成されたクラスに対しては作成されません。 3380 .LP 3381 \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 オプションも併せて指定しないかぎり、非公開のすべてのクラスやインタフェースにリンク経由でアクセスできるとはかぎりません。 3382 .LP 3383 各リンクは、その宣言内の識別子名の上に作成されます。たとえば、 \f2Button\fP クラスのソースコードへのリンクは、「Button」という語の上に作成されます。 3384 .nf 3385 \f3 3386 .fl 3387 public class Button 3388 .fl 3389 extends Component 3390 .fl 3391 implements Accessible 3392 .fl 3393 \fP 3394 .fi 3395 また、Button クラスの \f2getLabel()\fP メソッドのソースコードへのリンクは、「getLabel」という語の上に作成されます。 3396 .nf 3397 \f3 3398 .fl 3399 public String getLabel() 3400 .fl 3401 \fP 3402 .fi 3403 .LP 3404 .TP 3 3405 \-group\ groupheading\ packagepattern:packagepattern:... 3406 概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。各グループは、それぞれ別の \f2\-group\fP オプションで指定します。これらのグループは、コマンド行で指定した順序でページに表示されます。各グループ内では、パッケージがアルファベット順に並べられます。ある特定の \f2\-group\fP オプションでは、 \f2packagepattern\fP 式のリストに一致するパッケージが、 \f2groupheading\fP という見出しの表に表示されます。 3407 .RS 3 3408 .TP 2 3409 o 3410 \f4groupheading\fP には、任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。 3411 .TP 2 3412 o 3413 \f4packagepattern\fP には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (\f2*\fP) を指定できます。 アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして指定できるのは、アスタリスクだけです。1 つのグループには、コロン (\f2:\fP) で区切って複数のパターンを含めることができます。 3414 .RE 3415 .LP 3416 \f3注: パターンやパターンリスト内でアスタリスクを使う場合は、 \fP\f4"java.lang*:java.util" のように、パターンリストを引用符で囲む必要があります。\fP 3417 .LP 3418 ユーザーが \f2\-group\fP オプションを 1 つも指定しなかった場合、「パッケージ」という見出しの 1 つのグループ内に、すべてのパッケージが配置されます。ドキュメント化されるパッケージの中に、指定したグループのどのグループにも入らないパッケージがある場合、このようなパッケージは「その他のパッケージ」という見出しを持つ独立したグループに入れられます。 3419 .LP 3420 たとえば、次のようにオプションを指定すると、ドキュメント化される 5 つのパッケージは、コアパッケージ、拡張機能パッケージ、およびその他のパッケージに分けられます。「java.lang*」では、最後のドットを指定していないことに注目してください。「java.lang.*」のようにドットを入れると、java.lang パッケージは除外されることになります。 3421 .nf 3422 \f3 3423 .fl 3424 % \fP\f3javadoc \-group "Core Packages" "java.lang*:java.util" 3425 .fl 3426 \-group "Extension Packages" "javax.*" 3427 .fl 3428 java.lang java.lang.reflect java.util javax.servlet java.new\fP 3429 .fl 3430 .fi 3431 この結果、次のようなグループ化が行われます。 3432 .RS 3 3433 .TP 3 3434 コアパッケージ 3435 \f2java.lang\fP 3436 \f2java.lang.reflect\fP 3437 \f2java.util\fP 3438 .TP 3 3439 拡張機能パッケージ 3440 \f2javax.servlet\fP 3441 .TP 3 3442 その他のパッケージ 3443 \f2java.new\fP 3444 .RE 3445 .LP 3446 .TP 3 3447 \-nodeprecated 3448 推奨されない API をドキュメントに生成しないようにします。このオプションを指定すると、\-nodeprecatedlist オプションを指定した場合と同じ効果があることに加えて、ドキュメントのほかの部分全体でも、推奨されない API が生成されません。このオプションは、コードを記述しているとき、推奨されないコードによって気を散らされたくない場合に便利です。 3449 .LP 3450 .TP 3 3451 \-nodeprecatedlist 3452 推奨されない API のリストを含むファイル (deprecated\-list.html)、およびナビゲーションバーのそのページへのリンクが生成されないようにします。ただし、ドキュメントのほかの部分では、推奨されない API が生成されます。このオプションは、推奨されない API がソースコードに含まれておらず、ナビゲーションバーをすっきりと見せたい場合に便利です。 3453 .LP 3454 .TP 3 3455 \-nosince 3456 生成ドキュメントから、@since タグに対応する「導入されたバージョン」 セクションを省略します。 3457 .LP 3458 .TP 3 3459 \-notree 3460 生成されるドキュメントからクラスおよびインタフェースの階層ページを省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。デフォルトでは、階層が生成されます。 3461 .LP 3462 .TP 3 3463 \-noindex 3464 生成ドキュメントから、索引を省略します。デフォルトでは、索引が生成されます。 3465 .LP 3466 .TP 3 3467 \-nohelp 3468 出力の各ページの最上部と最下部にあるナビゲーションバーから「ヘルプ」リンクを省略します。 3469 .LP 3470 .TP 3 3471 \-nonavbar 3472 生成されるページの最上部と最下部に表示されるナビゲーションバー、ヘッダー、およびフッターを生成しないようにします。このオプションは、bottom オプションには影響を与えません。 \f2\-nonavbar\fP オプションは、印刷するためだけにファイルを PostScript または PDF に変換する場合など、内容だけが重要で、ナビゲーションの必要がない場合に便利です。 3473 .LP 3474 .TP 3 3475 \-helpfile\ path/filename 3476 上部と下部のナビゲーションバーの「ヘルプ」リンクのリンク先となる代替ヘルプファイル \f2path/filename\fP のパスを指定します。このオプションが指定されないと、Javadoc ツールは、ツール内でハードコードされているヘルプファイル \f2help\-doc.html\fP を自動作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。\f2filename\fP にはどんなファイル名でも指定でき、 \f2help\-doc.html には限定されません。\fP Javadoc ツールは、ナビゲーションバー内のリンクを必要に応じて調整します。次に例を示します。 3477 .nf 3478 \f3 3479 .fl 3480 % \fP\f3javadoc \-helpfile /home/user/myhelp.html java.awt\fP 3481 .fl 3482 .fi 3483 .TP 3 3484 \-stylesheetfile\ path/filename 3485 代替 HTML スタイルシートファイルのパスを指定します。このオプションが指定されないと、Javadoc ツールは、ツール内でハードコードされているスタイルシートファイル \f2stylesheet.css\fP を自動作成します。このオプションを使うと、そのデフォルトの動作をオーバーライドできます。\f2filename\fP にはどんなファイル名でも指定でき、 \f2stylesheet.css には限定されません\fP。たとえば、 3486 .nf 3487 \f3 3488 .fl 3489 % \fP\f3javadoc \-stylesheetfile /home/user/mystylesheet.css com.mypackage\fP 3490 .fl 3491 .fi 3492 .TP 3 3493 \-serialwarn 3494 @serial タグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1.2.2 以降のバージョンでは、直列化の警告は生成されません1.2.2 より前の初期バージョンでは、警告が生成されます。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと \f2writeExternal\fP メソッドを適切にドキュメント化するのに役立ちます。 3495 .LP 3496 .TP 3 3497 \-charset\ name 3498 このドキュメント用の HTML 文字セットを指定します。この名前は、 3499 .na 3500 \f2IANA Registry\fP @ 3501 .fi 3502 http://www.iana.org/assignments/character\-sets で与えられた、推奨される MIME 名でなければなりません。たとえば、 3503 .nf 3504 \f3 3505 .fl 3506 % \fP\f3javadoc \-charset "iso\-8859\-1" mypackage\fP 3507 .fl 3508 .fi 3509 生成されるすべてのページの先頭に、次の行が挿入されます。 3510 .nf 3511 \f3 3512 .fl 3513 <META http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1"> 3514 .fl 3515 \fP 3516 .fi 3517 この META タグについては、 3518 .na 3519 \f2HTML の標準\fP @ 3520 .fi 3521 http://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2 (4197265 および 4137321) を参照してください。 3522 .LP 3523 \-encoding および \-docencoding も参照してください。 3524 .LP 3525 .TP 3 3526 \-docencoding\ name 3527 生成される HTML ファイルのエンコーディングを指定します。この名前は、 3528 .na 3529 \f2IANA Registry\fP @ 3530 .fi 3531 http://www.iana.org/assignments/character\-sets で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら \-encoding を使用した場合、生成される HTML ファイルのエンコードは、\-encoding によって決められます。例: 3532 .nf 3533 \f3 3534 .fl 3535 % \fP\f3javadoc \-docencoding "ISO\-8859\-1" mypackage\fP 3536 .fl 3537 .fi 3538 \-encoding および \-charset も参照してください。 3539 .LP 3540 .TP 3 3541 \-keywords 3542 HTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。 3543 .LP 3544 メタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。 3545 .nf 3546 \f3 3547 .fl 3548 <META NAME="keywords" CONTENT="java.lang.String class"> 3549 .fl 3550 <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER"> 3551 .fl 3552 <META NAME="keywords" CONTENT="length()"> 3553 .fl 3554 <META NAME="keywords" CONTENT="charAt()"> 3555 .fl 3556 \fP 3557 .fi 3558 .LP 3559 .TP 3 3560 \-tag\ \ tagname:Xaoptcmf:"taghead" 3561 Javadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブロックタグ \f2@\fP\f2tagname\fP を解釈できるようにします。Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内に存在するすべてのカスタムタグについて、 \f2\-tag\fP オプションを含めることが重要です。今回の実行では出力されないタグは、X を付けて無効 \f2にします\fP。 3562 .LP 3563 コロン (\f4:\fP) が常に区切り文字になります。tagname \f2でコロンを使用する方法については、\fP 「タグ名でのコロンの使用」を参照してください。 3564 .LP 3565 \f2\-tag\fP オプションは、タグの見出し「taghead」を太字で出力します。 その次の行には、このオプションの引数で指定したテキストが続きます。 以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ ( \f2@return\fP や \f2@author\fP など) の出力とよく似ています。\f2taghead\fP を省略すると、\f2tagname\fP が見出しとして表示されます。 3566 .LP 3567 \f3タグの配置\fP \- 引数の \f4Xaoptcmf\fP 部分は、ソースコード内のタグを配置できる位置と、 を使ってこのタグを無効にできるかどうかを特定します。 \f2X\fP). タグの配置位置を制限しない場合は \f4a\fP を指定します。それ以外の文字の組み合わせも可能です。 \f4X\fP (タグの無効化) 3568 .br 3569 \f4a\fP (すべて) 3570 .br 3571 \f4o\fP (概要) 3572 .br 3573 \f4p\fP (パッケージ) 3574 .br 3575 \f4t\fP (型、つまりクラスとインタフェース) 3576 .br 3577 \f4c\fP (コンストラクタ) 3578 .br 3579 \f4m\fP (メソッド) 3580 .br 3581 \f4f\fP (フィールド) 3582 .LP 3583 \f3シングルタグの例\fP \- ソースコード内の任意の位置で使用できるタグのタグオプションの例を示します。 3584 .nf 3585 \f3 3586 .fl 3587 \-tag todo:a:"To Do:" 3588 .fl 3589 \fP 3590 .fi 3591 @todo をコンストラクタ、メソッド、フィールドのみで使用する場合は、以下のオプションを使用します。 3592 .nf 3593 \f3 3594 .fl 3595 \-tag todo:cmf:"To Do:" 3596 .fl 3597 \fP 3598 .fi 3599 上の例の最後のコロン (\f2:\fP) は、パラメータ区切り子ですが、見出しテキストの一部になっています (以下の例を参照)。次の例のように、 \f2@todo\fP タグを含むソースコードでは、いずれかのタグオプションを使用します。 3600 .nf 3601 \f3 3602 .fl 3603 @todo The documentation for this method needs work. 3604 .fl 3605 \fP 3606 .fi 3607 \f3タグ名にコロンを使用する\fP \- コロン (:) をバックスラッシュでエスケープすると、コロンをタグ名に使用することができます。このドキュメンテーションコメントの中では、次のように使用します。 3608 .nf 3609 \f3 3610 .fl 3611 /** 3612 .fl 3613 * @ejb:bean 3614 .fl 3615 */ 3616 .fl 3617 \fP 3618 .fi 3619 でこのタグオプションを使用すると、 3620 .nf 3621 \f3 3622 .fl 3623 \-tag ejb\\\\:bean:a:"EJB Bean:" 3624 .fl 3625 \fP 3626 .fi 3627 \f3タグ名のスペルチェック (タグの無効化)\fP \- ソースコード内に配置した一部のカスタムタグの出力を抑制したい場合があります。この場合も、ソースコード内にすべてのタグを配置し、出力を抑制しないタグを有効にし、出力を抑制するタグを無効にします。 \f2X\fP が存在する場合はタグが無効になり、存在しない場合はタグが有効になります。これにより、Javadoc ツールは、検出したタグが入力ミスなどによる未知のタグであるかどうかを特定できます。未知のタグを検出した場合、Javadoc ツールは警告を出力します。 3628 .LP 3629 すでに配置されている値に \f2X\fP を追加できます。こうしておけば、 \f2X を削除するだけでタグを有効にすることができます\fP。たとえば、@todo タグの出力を抑制したい場合、次のように指定します。 3630 .nf 3631 \f3 3632 .fl 3633 \-tag todo:Xcmf:"To Do:" 3634 .fl 3635 \fP 3636 .fi 3637 さらに単純な指定方法もあります。 3638 .nf 3639 \f3 3640 .fl 3641 \-tag todo:X 3642 .fl 3643 \fP 3644 .fi 3645 .LP 3646 構文 \f2\-tag todo:X\fP は、 \f2@todo\fP がタグレットで定義されていても有効です。 3647 .LP 3648 \f3タグの順序\fP \- \f2\-tag\fP (および \f2\-taglet\fP) オプションの順序によって、タグの出力順が決まります。カスタムタグと標準タグを組み合わせて使用することもできます。標準タグのタグオプションは、順序を決定するためだけのプレースホルダです。これらは標準タグ名のみを使用します。(標準タグの小見出しは変更できません。)これについては、以下の例で説明します。 3649 .LP 3650 \f2\-tag\fP が存在しない場合は、 \f2\-taglet\fP の位置によってその順序が決まります。タグが両方とも存在する場合、コマンド行の最後にあるほうがその順序を決定します。これは、タグやタグレットがコマンド行に指定された順番に処理されるためです。たとえば、 \f2\-taglet\fP と \f2\-tag\fP の両方が todo という名前を持っている場合、コマンド行の最後にあるほうが順序を決定します。 3651 .LP 3652 \f3タグの完全セットの例\fP \- この例では、出力の「Parameters」と「Throws」の間に「To Do」を挿入します。X を使用して、@example が、ソースコード内の今回の実行では出力されないタグであることを指定します。@argfile を使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます。行の継続を示す文字は不要です。 3653 .nf 3654 \f3 3655 .fl 3656 \-tag param 3657 .fl 3658 \-tag return 3659 .fl 3660 \-tag todo:a:"To Do:" 3661 .fl 3662 \-tag throws 3663 .fl 3664 \-tag see 3665 .fl 3666 \-tag example:X 3667 .fl 3668 \fP 3669 .fi 3670 .LP 3671 javadoc がドキュメンテーションコメントを解析する際に検索されたタグのうち、標準タグでも、 \f2\-tag\fP や \f2\-taglet\fP で渡されたタグでもないものはすべて未知のタグとみなされ、警告がスローされます。 3672 .LP 3673 標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。 \f2\-tag\fP オプションを使用すると、このリストに追加されるタグ、すなわち標準タグの位置がデフォルトの位置から移動します。つまり、標準タグに \f2\-tag\fP オプションを付けなければ、これらはデフォルトの位置に配置されたままになります。 3674 .LP 3675 \f3競合の回避\fP \- 固有の名前空間を細かく分けるには、パッケージに使用されている \f2com.mycompany.todo という名前のように、ドット (.) を区切り記号とする名前を使います\fP。Oracle は、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Oracle が提供する同じ名前のタグの動作をオーバーライドします。つまり、 \f2@todo\fP という名前のタグまたはタグレットをユーザーが作成した場合、Oracle がその後同じ名前の標準タグを作成したとしても、その動作は常にユーザーが定義した動作と同じになります。 3676 .LP 3677 \f3注釈 vs. Javadoc タグ\fP \- 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。それ以外の場合は注釈にすべきです。 3678 .na 3679 \f2「Comparing Annotations and Javadoc Tags」\fP @ 3680 .fi 3681 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#annotationsを参照してください。 3682 .LP 3683 \-taglet オプションを使用して、より複雑なブロックタグやカスタムインラインタグを 作成することができます。 3684 .LP 3685 .TP 3 3686 \-taglet\ \ class 3687 そのタグのドキュメントの生成に使うドックレットを起動するためのクラスファイルを指定します。クラスの完全指定名を指定してください。このタグレットは、カスタムタグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。外部ドキュメントとサンプルタグレットについては、以下を参照してください。 3688 .RS 3 3689 .TP 2 3690 o 3691 .na 3692 \f2「タグレットの概要」\fP @ 3693 .fi 3694 http://java.sun.com/javase/6/docs/technotes/guides/javadoc/taglet/overview.html 3695 .RE 3696 .LP 3697 タグレットは、ブロックタグまたはインラインタグで便利です。タグレットは任意の数の引数をとることができます。また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。 3698 .LP 3699 タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。 3700 .LP 3701 タグレットのパスを指定するには、\f2\-tagletpath\fP オプションを使用します。以下は、生成されるページの「Parameter」と「Throws」の間に「To Do」タグレットを挿入する例です。 3702 .nf 3703 \f3 3704 .fl 3705 \-taglet com.sun.tools.doclets.ToDoTaglet 3706 .fl 3707 \-tagletpath /home/taglets 3708 .fl 3709 \-tag return 3710 .fl 3711 \-tag param 3712 .fl 3713 \-tag todo 3714 .fl 3715 \-tag throws 3716 .fl 3717 \-tag see 3718 .fl 3719 \fP 3720 .fi 3721 .LP 3722 また、 \f2\-taglet\fP オプションを \f2\-tag\fP オプションの代わりに使用することもできますが、そうすると可読性が低下する可能性があります。 3723 .LP 3724 .TP 3 3725 \-tagletpath\ \ tagletpathlist 3726 taglet クラスファイル (.class) の検索パスを指定します。\f2tagletpathlist\fP には、コロン (\f2:\fP) で区切って複数のパスを含めることができます。Javadoc ツールは、指定されたパス以下のすべてのサブディレクトリを検索します。 3727 .LP 3728 .TP 3 3729 \-docfilessubdirs\ 3730 「\f2doc\-files\fP」ディレクトリの深いコピーを有効にします。つまり、コピー先には、サブディレクトリとすべてのコンテンツがコピーされます。たとえば、ディレクトリ \f2doc\-files/example/images\fP とそのすべての内容がコピーされます。ここでも、サブディレクトリを除外する指定が可能です。 3731 .LP 3732 .TP 3 3733 \-excludedocfilessubdir\ \ name1:name2... 3734 「\f2doc\-files\fP」の、指定された名前のサブディレクトリをすべて除外します。これにより、SCCS とその他のソースコード制御サブディレクトリのコピーを防ぎます。 3735 .LP 3736 .TP 3 3737 \-noqualifier\ \ all\ | \ packagename1:packagename2:... 3738 出力されるクラス名の先頭のパッケージ名 (パッケージ修飾子) を省略します。 \f2\-noqualifier\fP の引数は、「\f2all\fP」(すべてのパッケージ修飾子が省略される)、修飾子として削除すべきパッケージのコロン区切りリスト (ワイルドカードも可)、のいずれかとなります。クラスまたはインタフェース名が表示される位置からパッケージ名が削除されます。 3739 .LP 3740 次の例では、すべてのパッケージ修飾子を省略します。 3741 .nf 3742 \f3 3743 .fl 3744 \-noqualifier all 3745 .fl 3746 \fP 3747 .fi 3748 次の例では、パッケージ修飾子 java.lang および java.io を省略します。 3749 .nf 3750 \f3 3751 .fl 3752 \-noqualifier java.lang:java.io 3753 .fl 3754 \fP 3755 .fi 3756 次の例では、java で始まるパッケージ修飾子と com.sun というサブパッケージ (javax ではない) を省略します。 3757 .nf 3758 \f3 3759 .fl 3760 \-noqualifier java.*:com.sun.* 3761 .fl 3762 \fP 3763 .fi 3764 パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。詳細は「名前の表示方法」を参照してください。この規則は、 \f2\-noqualifier\fP を使用するかどうかにかかわらず有効です。 3765 .LP 3766 .TP 3 3767 \-notimestamp\ 3768 タイムスタンプが抑制されます。各ページ先頭近くにある、生成された HTML 内の HTML コメントでタイムスタンプが隠されます。Javadoc を 2 つのソースベースで実行し、それらに対して diff を実行するときにこのオプションを使用すると、タイムスタンプによって diff が発生しなくなるので便利です (このオプションを使用しないと、各ページで diff になります)。タイムスタンプには Javadoc のバージョン番号が含まれており、次のようになります。 3769 .nf 3770 \f3 3771 .fl 3772 <!\-\- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 \-\-> 3773 .fl 3774 \fP 3775 .fi 3776 .LP 3777 .TP 3 3778 \-nocomment\ 3779 主説明およびすべてのタグを含むコメント本文全体を抑制し、宣言だけを生成します。このオプションにより、元は異なる目的のためだったソースファイルを再利用し、新しいプロジェクトの早い段階でスケルトン HTML ドキュメントを作成できるようになりました。 3780 .LP 3781 .TP 3 3782 \-sourcetab tabLength 3783 ソース内で各タブが獲得する空白の数を指定します。 3784 .RE 3785 .SH "コマンド行引数ファイル" 3786 .LP 3787 javadoc のコマンド行を短くしたり簡潔にしたりするために、 \f2javadoc\fP コマンドに対する引数 ( \f2\-J\fP オプションを除く) が入った 1 つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティングシステム上でも、任意の長さの javadoc コマンドを作成できます。 3788 .LP 3789 引数ファイルには、javac のオプションとソースファイル名を自由に組み合わせて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲みます。 3790 .LP 3791 引数ファイル内のファイル名は、現在のディレクトリから見た相対パスになります。引数ファイルの位置から見た相対パスではありません。引数ファイル内のファイル名リストでは、ワイルドカード (*) は使用できません。たとえば、 \f2*.java\fP とは指定できません。引数ファイル内の引数で \f2@\fP 文字を使用して、複数のファイルを再帰的に解釈することはサポートされていません。また、 \f2\-J\fP オプションもサポートされていません。 このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。 3792 .LP 3793 javadoc を実行するときに、各引数ファイルのパスとファイル名の先頭に \f2@\fP 文字を付けて渡します。javadoc は、\f2@\fP 文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。 3794 .SS 3795 引数ファイルを 1 つ指定する例 3796 .LP 3797 次のように、「\f2argfile\fP」という名前の単一の引数ファイル内に、Javadoc のすべての引数を格納します。 3798 .nf 3799 \f3 3800 .fl 3801 % \fP\f3javadoc @argfile\fP 3802 .fl 3803 .fi 3804 .LP 3805 この引数ファイルには、次の例で示されている 2 つのファイルの内容を両方とも入れることができます。 3806 .SS 3807 引数ファイルを 2 つ指定する例 3808 .LP 3809 2 つの引数ファイルを作成できます。1 つは Javadoc オプション用、もう 1 つはパッケージ名またはソースファイル名用です。なお、次のリストでは行継続文字を使用していません。 3810 .LP 3811 次の内容を含む、「\f2options\fP」という名前のファイルを作成します。 3812 .nf 3813 \f3 3814 .fl 3815 \-d docs\-filelist 3816 .fl 3817 \-use 3818 .fl 3819 \-splitindex 3820 .fl 3821 \-windowtitle 'Java SE 7 API Specification' 3822 .fl 3823 \-doctitle 'Java SE 7 API Specification' 3824 .fl 3825 \-header '<b>Java(TM) SE 7</b>' 3826 .fl 3827 \-bottom 'Copyright © 1993\-2011 Oracle and/or its affiliates. All rights reserved.' 3828 .fl 3829 \-group "Core Packages" "java.*" 3830 .fl 3831 \-overview /java/pubs/ws/1.7.0/src/share/classes/overview\-core.html 3832 .fl 3833 \-sourcepath /java/pubs/ws/1.7.0/src/share/classes 3834 .fl 3835 \fP 3836 .fi 3837 .LP 3838 次の内容を含む、「\f2packages\fP」という名前のファイルを作成します。 3839 .nf 3840 \f3 3841 .fl 3842 com.mypackage1 3843 .fl 3844 com.mypackage2 3845 .fl 3846 com.mypackage3 3847 .fl 3848 \fP 3849 .fi 3850 .LP 3851 そのあと、次のコマンドを使用して javadoc を実行します。 3852 .nf 3853 \f3 3854 .fl 3855 % \fP\f3javadoc @options @packages\fP 3856 .fl 3857 .fi 3858 .SS 3859 パス付きの引数ファイルの例 3860 .LP 3861 引数ファイルには、パスを指定できます。ただし、そのファイル内に指定されたファイル名は、現在の作業ディレクトリから見た相対パスになります。つまり、下の例の場合は、 \f2path1\fP や \f2path2\fP から見た相対パスではありません。 3862 .nf 3863 \f3 3864 .fl 3865 % \fP\f3javadoc @path1/options @path2/packages\fP 3866 .fl 3867 .fi 3868 .SS 3869 オプションの引数の例 3870 .LP 3871 次に、Javadoc オプションに対する引数だけを引数ファイルに格納する例を示します。ここでは \f2\-bottom\fP オプションを使用します。というのも、引数が長くなる可能性があるからです。次のようなテキスト引数を含む、「\f2bottom\fP」という名前のファイルを作成できます。 3872 .nf 3873 \f3 3874 .fl 3875 <font size="\-1"> 3876 .fl 3877 <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/> 3878 .fl 3879 Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/> 3880 .fl 3881 Oracle is a registered trademark of Oracle Corporation and/or its affiliates. 3882 .fl 3883 その他の名称は、それぞれの所有者の商標または登録商標です。</font> 3884 .fl 3885 \fP 3886 .fi 3887 .LP 3888 そのあと、次のようにして Javadoc ツールを実行します。 3889 .nf 3890 \f3 3891 .fl 3892 % \fP\f3javadoc \-bottom @bottom @packages\fP 3893 .fl 3894 .fi 3895 .LP 3896 あるいは、引数ファイルの先頭に \f2\-bottom\fP オプションも組み込んだあと、次のように実行してもかまいません。 3897 .nf 3898 \f3 3899 .fl 3900 % \fP\f3javadoc @bottom @packages\fP 3901 .fl 3902 .fi 3903 .SH "名前" 3904 実行 3905 .SH "Javadoc の実行" 3906 .LP 3907 \f3バージョン番号\fP \- javadoc のバージョン番号を判別するには、\f3javadoc \-J\-version\fP を使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。その出力を無効にするには、 \f2\-quiet\fP を使用します。 3908 .LP 3909 \f3公開プログラムインタフェース\fP \- Java 言語で記述されたプログラムから Javadoc ツールを起動するとき使用します。このインタフェースは \f2com.sun.tools.javadoc.Main にあります\fP (javadoc は再入可能)。詳細は、 3910 .na 3911 \f2「標準ドックレット」\fP @ 3912 .fi 3913 http://java.sun.com/javase/6/docs/technotes/guides/javadoc/standard\-doclet.html#runningprogrammaticallyを参照してください。 3914 .LP 3915 \f3ドックレットの実行\fP \- 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、\-doclet および \-docletpath オプションを使用します。特定のドックレットを実行した完全な例については、 3916 .na 3917 \f2MIF Doclet のドキュメント\fP @ 3918 .fi 3919 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.htmlを参照してください。 3920 .SH "簡単な例" 3921 .LP 3922 javadoc は、パッケージ全体に対して実行することも、個々のソースファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。次の例では、ソースファイルは \f2/home/src/java/awt/*.java にあります\fP。生成先ディレクトリは \f2/home/html です\fP。 3923 .SS 3924 1 つ以上のパッケージのドキュメント化 3925 .LP 3926 あるパッケージをドキュメント化するには、そのパッケージのソースファイル (\f2*.java\fP) を、そのパッケージと同じ名前のディレクトリ内に格納する必要があります。パッケージ名が ( \f2java.awt.color\fP のようにドットで区切られた) いくつかの識別子から構成されている場合、右側の識別子に進むたびに、その識別子がより深いサブディレクトリに対応している必要があります ( \f2java/awt/color\fP など)。 単一パッケージのソースファイルを 2 グループに分け、異なる場所にあるそのような 2 つのディレクトリツリー内にそれぞれ格納してもかまいません。ただし、その両方のディレクトリへのパスを、 \f2\-sourcepath\fP に設定する必要があります。例: \f2src1/java/awt/color\fP および \f2src2/java/awt/color\fP。 3927 .LP 3928 javadoc を実行するには、 \f2cd\fP を使用してディレクトリを変更するか、 \f2\-sourcepath\fP オプションを使用します。以下の例では、両方の方法について説明します。 3929 .RS 3 3930 .TP 2 3931 o 3932 \f3ケース 1 \- 1 つ以上のパッケージからの起動を再帰的に実行\fP \- この例では javadoc が任意のディレクトリから実行できるように、\-sourcepath を使用し、再帰的処理のために \-subpackages (1.4 の新オプション) を使用します。これは、 \f2java\fP ディレクトリのサブパッケージをたどりますが、その際に、 \f2java.net\fP と \f2java.lang\fP をルートに持つパッケージが除外されます。この場合、 \f2java.lang\fP のサブパッケージである \f2java.lang.ref\fP。 3933 .nf 3934 \f3 3935 .fl 3936 % \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 3937 .fl 3938 .fi 3939 .LP 3940 ほかのパッケージツリーも下方にたどるには、 \f2java:javax:org.xml.sax のように、\fP それらのパッケージの名前を \-subpackages \f2の引数の末尾に追加します\fP。 3941 .TP 2 3942 o 3943 \f3ケース 2 \- ルートソースディレクトリに移ってから明示的なパッケージに対して実行\fP \- 完全指定のパッケージ名の親ディレクトリに移ります。次に、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。 3944 .nf 3945 \f3 3946 .fl 3947 % \fP\f3cd /home/src/\fP 3948 .fl 3949 % \f3javadoc \-d /home/html java.awt java.awt.event\fP 3950 .fl 3951 .fi 3952 .TP 2 3953 o 3954 \f3ケース 3 \- 任意のディレクトリから実行。ソースファイルは 1 つのディレクトリツリー内にある\fP \- このケースでは、現在のディレクトリがどこであってもかまいません。最上位パッケージの親ディレクトリを \f2\-sourcepath\fP に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。 3955 .nf 3956 \f3 3957 .fl 3958 % \fP\f3javadoc \-d /home/html \-sourcepath /home/src java.awt java.awt.event\fP 3959 .fl 3960 .fi 3961 .TP 2 3962 o 3963 \f3ケース 4 \- 任意のディレクトリから実行。ソースファイルは複数のディレクトリツリー内にある\fP \- これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに存在します。それぞれのツリーのルートへのパスを \f2\-sourcepath\fP に指定し (コロンで区切る)、ドキュメント化する 1 つ以上のパッケージ名を指定して javadoc を実行します。1 つのパッケージのすべてのソースファイルが、1 つのルートディレクトリの下に存在しなければならない、ということはありません。ソースパスとして指定された場所のどこかで見つかれば十分です。 3964 .nf 3965 \f3 3966 .fl 3967 % \fP\f3javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java.awt java.awt.event\fP 3968 .fl 3969 .fi 3970 .RE 3971 .LP 3972 結果: すべてのケースでパッケージ \f2java.awt\fP および \f2java.awt.event\fP 内の public および protected クラスとインタフェースについて、HTML 形式のドキュメントが生成され、指定された生成先ディレクトリ (\f2/home/html\fP) に HTML ファイルが保存されます。2 つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラスページという 3 つのフレームを持つことになります。 3973 .SS 3974 1 つ以上のクラスのドキュメント化 3975 .LP 3976 また、1 つ以上のソースファイル (\f2.java\fP) を渡して、Javadoc ツールを実行することもできます。javadoc は、次の 2 つの方法のいずれかで実行できます。1 つは \f2cd\fP を使用してディレクトリを変更する方法、もう 1 つは \f2.java\fP ファイルへのパスを完全に指定する方法です。相対パスは、現在のディレクトリを起点とします。ソースファイル名を渡すときは、 \f2\-sourcepath\fP オプションは無視されます。アスタリスク (*) のようなコマンド行ワイルドカードを使用すると、クラスのグループを指定できます。 3977 .RS 3 3978 .TP 2 3979 o 3980 \f3ケース 1 \- ソースディレクトリに移る\fP \- \f2.java\fP ファイルのあるディレクトリに移ります。次に、ドキュメント化する 1 つ以上のソースファイルの名前を指定して javadoc を実行します。 3981 .nf 3982 \f3 3983 .fl 3984 % \fP\f3cd /home/src/java/awt\fP 3985 .fl 3986 % \f3javadoc \-d /home/html Button.java Canvas.java Graphics*.java\fP 3987 .fl 3988 .fi 3989 この例では、クラス \f2Button\fP と \f2Canvas\fP 、および名前が \f2Graphics で始まるクラスについて、HTML 形式のドキュメントが生成されます\fP。パッケージ名ではなくソースファイルが javadoc に引数として渡されているので、ドキュメントは、クラスのリストとメインページという 2 つのフレームを持つことになります。 3990 .TP 2 3991 o 3992 \f3ケース 2 \- パッケージのルートディレクトリに移る\fP \- これは、同じルート内にある複数のサブパッケージの個々のソースファイルをドキュメント化する場合に便利です。パッケージのルートディレクトリに移り、各ソースファイルを、ルートからのパスとともに指定します。 3993 .nf 3994 \f3 3995 .fl 3996 % \fP\f3cd /home/src/\fP 3997 .fl 3998 % \f3javadoc \-d /home/html java/awt/Button.java java/applet/Applet.java\fP 3999 .fl 4000 .fi 4001 この例では、クラス \f2Button\fP および \f2Applet について、HTML 形式のドキュメントが生成されます\fP。 4002 .TP 2 4003 o 4004 \f3ケース 3 \- 任意のディレクトリから\fP \- このケースでは、現在のディレクトリがどこであってもかまいません。ドキュメント化する .java ファイルへの絶対パス (またはカレントディレクトリからの相対パス) を指定して \f2javadoc\fP を実行します。 4005 .nf 4006 \f3 4007 .fl 4008 % \fP\f3javadoc \-d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java\fP 4009 .fl 4010 .fi 4011 この例では、クラス \f2Button\fP と、名前が \f2Graphics で始まるクラスについて、HTML 形式のドキュメントが生成されます\fP。 4012 .RE 4013 .SS 4014 パッケージとクラスのドキュメント化 4015 .LP 4016 パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に前述の 2 つの例を組み合わせた例を示します。 \f2\-sourcepath\fP は、パッケージへのパスに対しては使用できますが、個々のクラスのパスに対しては使用できません。 4017 .nf 4018 \f3 4019 .fl 4020 % \fP\f3javadoc \-d /home/html \-sourcepath /home/src java.awt /home/src/java/applet/Applet.java\fP 4021 .fl 4022 .fi 4023 .LP 4024 この例では、パッケージ \f2java.awt\fP とクラス \f2Applet について、HTML 形式のドキュメントが生成されます\fP。Javadoc ツールは、 \f2Applet.java ソースファイル内にパッケージ宣言があれば、\fP その宣言に基づいて \f2Applet のパッケージ名を\fP 判定します。 4025 .SH "使用例" 4026 .LP 4027 Javadoc ツールには多くの便利なオプションがあり、その中にはほかのオプションよりも頻繁に使われるものがあります。ここで紹介するのは、Java プラットフォーム API に対して Javadoc ツールを実行するときに使用する実際のコマンドです。ここでは、Java SE Platform, Standard Edition, v1.2 の (約) 1500 個の public および protected クラスのドキュメントを生成するために、180M バイトのメモリーを使用します。 4028 .LP 4029 同じ例を 2 回掲載します。最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。オプションの引数で絶対パスが使用されているため、同じ \f2javadoc\fP コマンドをどのディレクトリからでも実行できます。 4030 .SS 4031 コマンド行の例 4032 .LP 4033 次の例は、DOS などの一部のシェルでは長すぎる可能性があります。この制限を回避するには、コマンド行引数ファイルを使用します。または、シェルスクリプトを記述します。 4034 .nf 4035 \f3 4036 .fl 4037 % javadoc \-sourcepath /java/jdk/src/share/classes \\ 4038 .fl 4039 \-overview /java/jdk/src/share/classes/overview.html \\ 4040 .fl 4041 \-d /java/jdk/build/api \\ 4042 .fl 4043 \-use \\ 4044 .fl 4045 \-splitIndex \\ 4046 .fl 4047 \-windowtitle 'Java Platform, Standard Edition 7 API Specification' \\ 4048 .fl 4049 \-doctitle 'Java Platform, Standard Edition 7 API Specification' \\ 4050 .fl 4051 \-header '<b>Java(TM) SE 7</b>' \\ 4052 .fl 4053 \-bottom '<font size="\-1"> 4054 .fl 4055 <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/> 4056 .fl 4057 Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/> 4058 .fl 4059 Oracle is a registered trademark of Oracle Corporation and/or its affiliates. 4060 .fl 4061 その他の名称は、それぞれの所有者の商標または登録商標です。</font>' \\ 4062 .fl 4063 \-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \\ 4064 .fl 4065 \-group "Extension Packages" "javax.*" \\ 4066 .fl 4067 \-J\-Xmx180m \\ 4068 .fl 4069 @packages 4070 .fl 4071 \fP 4072 .fi 4073 .LP 4074 ここで、 \f2packages\fP は、処理対象のパッケージ名 ( \f2java.applet java.lang\fP など) が入っているファイルの名前です。各オプションの、単一引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー＆ペーストする場合は、 \f2\-bottom\fP オプションから改行文字を削除してください。さらに、このあとの「注」も参照してください。 4075 .SS 4076 Makefile の例 4077 .LP 4078 ここでは、GNU Makefile の例を示します。Windows の Makefile の例については、 4079 .na 4080 \f2Windows の Makefile の作成方法\fP @ 4081 .fi 4082 http://java.sun.com/j2se/javadoc/faq/index.html#makefilesを参照してください。 4083 .nf 4084 \f3 4085 .fl 4086 javadoc \-\fP\f3sourcepath\fP\f3 $(SRCDIR) \\ /* Sets path for source files */ 4087 .fl 4088 \-\fP\f3overview\fP\f3 $(SRCDIR)/overview.html \\ /* Sets file for overview text */ 4089 .fl 4090 \-\fP\f3d\fP\f3 /java/jdk/build/api \\ /* Sets destination directory */ 4091 .fl 4092 \-\fP\f3use\fP\f3 \\ /* Adds "Use" files */ 4093 .fl 4094 \-\fP\f3splitIndex\fP\f3 \\ /* Splits index A\-Z */ 4095 .fl 4096 \-\fP\f3windowtitle\fP\f3 $(WINDOWTITLE) \\ /* Adds a window title */ 4097 .fl 4098 \-\fP\f3doctitle\fP\f3 $(DOCTITLE) \\ /* Adds a doc title */ 4099 .fl 4100 \-\fP\f3header\fP\f3 $(HEADER) \\ /* Adds running header text */ 4101 .fl 4102 \-\fP\f3bottom\fP\f3 $(BOTTOM) \\ /* Adds text at bottom */ 4103 .fl 4104 \-\fP\f3group\fP\f3 $(GROUPCORE) \\ /* 1st subhead on overview page */ 4105 .fl 4106 \-\fP\f3group\fP\f3 $(GROUPEXT) \\ /* 2nd subhead on overview page */ 4107 .fl 4108 \-\fP\f3J\fP\f3\-Xmx180m \\ /* Sets memory to 180MB */ 4109 .fl 4110 java.lang java.lang.reflect \\ /* Sets packages to document */ 4111 .fl 4112 java.util java.io java.net \\ 4113 .fl 4114 java.applet 4115 .fl 4116 4117 .fl 4118 WINDOWTITLE = 'Java(TM) SE 7 API Specification' 4119 .fl 4120 DOCTITLE = 'Java(TM) Platform Standard Edition 7 API Specification' 4121 .fl 4122 HEADER = '<b>Java(TM) SE 7</font>' 4123 .fl 4124 BOTTOM = '<font size="\-1"> 4125 .fl 4126 <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/> 4127 .fl 4128 Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/> 4129 .fl 4130 Oracle is a registered trademark of Oracle Corporation and/or its affiliates. 4131 .fl 4132 その他の名称は、それぞれの所有者の商標または登録商標です。</font>' 4133 .fl 4134 GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"' 4135 .fl 4136 GROUPEXT = '"Extension Packages" "javax.*"' 4137 .fl 4138 SRCDIR = '/java/jdk/1.7.0/src/share/classes' 4139 .fl 4140 \fP 4141 .fi 4142 .LP 4143 Makefile の引数は、単一引用符で囲みます。 4144 .LP 4145 \f3注\fP 4146 .RS 3 4147 .TP 2 4148 o 4149 \-windowtitle \f2オプションを省略すると、\fP Javadoc ツールによってドキュメントタイトルがウィンドウタイトルにコピーされます。 \f2\-windowtitle\fP のテキストは基本的に \f2\-doctitle\fP のものと同じですが、HTML タグを含まない点が異なります。これは、HTML タグが raw テキストとしてウィンドウタイトル内に表示されるのを防ぐためです。 4150 .TP 2 4151 o 4152 ここで行っているように \f2\-footer\fP オプションを省略すると、Javadoc ツールによってヘッダーのテキストがフッターにコピーされます。 4153 .TP 2 4154 o 4155 この例では必要ありませんが、\-\f2classpath\fP と \-\f2link\fP も重要なオプションです。 4156 .RE 4157 .SH "トラブルシューティング" 4158 .SS 4159 一般的なトラブルシューティング 4160 .RS 3 4161 .TP 2 4162 o 4163 \f3Javadoc FAQ\fP \- 一般的なバグおよびトラブルシューティングのヒントは、 4164 .na 4165 \f2「Javadoc FAQ」\fP @ 4166 .fi 4167 http://java.sun.com/j2se/javadoc/faq/index.html#B で参照できます。 4168 .TP 2 4169 o 4170 \f3バグおよび制限事項\fP \- バグの一部は、「Important Bug Fixes and Changes」 でも参照できます。 4171 .TP 2 4172 o 4173 \f3バージョン番号\fP \- 「バージョン番号」を参照してください。 4174 .TP 2 4175 o 4176 \f3有効なクラスだけをドキュメント化\fP \- パッケージをドキュメント化するとき、Javadoc は、有効なクラス名で構成されているファイルのみを読み込みます。たとえば、ファイル名にハイフン「\-」を含めることで、javadoc によるファイルの解析を防ぐことができます。 4177 .RE 4178 .SS 4179 エラーと警告 4180 .LP 4181 エラーおよび警告メッセージには、ファイル名と宣言行 (ドキュメンテーションコメント内の特定の行ではない) の行番号が含まれます。 4182 .RS 3 4183 .TP 2 4184 o 4185 \f2"error: cannot read: Class1.java"\fP Javadoc ツールはカレントディレクトリに Class1.java クラスをロードしようとしています。絶対パスまたは相対パスとともに表示されるクラス名は、この例の場合 \f2./Class1.java と同じです\fP。 4186 .RE 4187 .SH "環境" 4188 .RS 3 4189 .TP 3 4190 CLASSPATH 4191 Javadoc がユーザークラスのファイルを探すときに使うパスを指定する環境変数です。この環境変数は、 \f2\-classpath\fP オプションによってオーバーライドされます。ディレクトリは、次のようにコロンで区切ります。 4192 .:/home/classes:/usr/local/java/classes 4193 .RE 4194 .SH "関連項目" 4195 .RS 3 4196 .TP 2 4197 o 4198 javac(1) 4199 .TP 2 4200 o 4201 java(1) 4202 .TP 2 4203 o 4204 jdb(1) 4205 .TP 2 4206 o 4207 javah(1) 4208 .TP 2 4209 o 4210 javap(1) 4211 .TP 2 4212 o 4213 .na 4214 \f2Javadoc のホームページ\fP @ 4215 .fi 4216 http://www.oracle.com/technetwork/java/javase/documentation/index\-jsp\-135444.html 4217 .TP 2 4218 o 4219 .na 4220 \f2How to Write Doc Comments for Javadoc\fP @ 4221 .fi 4222 http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html 4223 .TP 2 4224 o 4225 .na 4226 \f2クラスパスの設定\fP @ 4227 .fi 4228 http://java.sun.com/javase/6/docs/technotes/tools/index.html#general 4229 .TP 2 4230 o 4231 .na 4232 \f2javac と javadoc がクラスを検索する方法\fP @ 4233 .fi 4234 http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfiles (tools.jar) 4235 .RE 4236 | 1 '\" t 2 .\" Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved. 3 .\" Title: javadoc 4 .\" Language: English 5 .\" Date: 2011年5月10日 6 .\" SectDesc: 基本ツール 7 .\" Software: JDK 8 8 .\" Arch: 汎用 9 .\" 10 .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 11 .\" 12 .\" This code is free software; you can redistribute it and/or modify it 13 .\" under the terms of the GNU General Public License version 2 only, as 14 .\" published by the Free Software Foundation. 15 .\" 16 .\" This code is distributed in the hope that it will be useful, but WITHOUT 17 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 18 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 19 .\" version 2 for more details (a copy is included in the LICENSE file that 20 .\" accompanied this code). 21 .\" 22 .\" You should have received a copy of the GNU General Public License version 23 .\" 2 along with this work; if not, write to the Free Software Foundation, 24 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 25 .\" 26 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 27 .\" or visit www.oracle.com if you need additional information or have any 28 .\" questions. 29 .\" 30 .pl 99999 31 .TH "javadoc" "1" "2011年5月10日" "JDK 8" "基本ツール" 32 .\" ----------------------------------------------------------------- 33 .\" * Define some portability stuff 34 .\" ----------------------------------------------------------------- 35 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36 .\" http://bugs.debian.org/507673 37 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html 38 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 .ie \n(.g .ds Aq \(aq 40 .el .ds Aq ' 41 .\" ----------------------------------------------------------------- 42 .\" * set default formatting 43 .\" ----------------------------------------------------------------- 44 .\" disable hyphenation 45 .nh 46 .\" disable justification (adjust text to left margin only) 47 .ad l 48 .\" ----------------------------------------------------------------- 49 .\" * MAIN CONTENT STARTS HERE * 50 .\" ----------------------------------------------------------------- 51 .SH "NAME" 52 javadoc \- Javaソース・ファイルから、APIドキュメントのHTMLページを生成します。 53 .SH "概要" 54 .sp 55 .if n \{\ 56 .RS 4 57 .\} 58 .nf 59 \fIjavadoc\fR {\fIpackages\fR|\fIsource\-files\fR} [\fIoptions\fR] [\fI@argfiles\fR] 60 .fi 61 .if n \{\ 62 .RE 63 .\} 64 .PP 65 \fIpackages\fR 66 .RS 4 67 \fIjava\&.lang java\&.lang\&.reflect java\&.awt\fRなど、空白で区切ってドキュメント化するパッケージの名前。サブパッケージもドキュメント化する場合は、\fI\-subpackages\fRオプションを使用してパッケージを指定します。 68 .sp 69 デフォルトでは、\fIjavadoc\fRは、現在のディレクトリおよびサブディレクトリで指定されたパッケージを探します。\fI\-sourcepath\fRオプションを使用して、パッケージを探すディレクトリのリストを指定します。 70 .RE 71 .PP 72 \fIsource\-files\fR 73 .RS 4 74 \fIClass\&.java Object\&.java Button\&.java\fRのように空白で区切った、ドキュメント化するJavaソース・ファイルの名前。デフォルトでは、\fIjavadoc\fRは、現在のディレクトリで指定されたクラスを探します。ただし、\fI/home/src/java/awt/Graphics*\&.java\fRのように、クラス・ファイルのフルパスを指定し、ワイルドカード文字を使用できます。現在のディレクトリからの相対パスも指定できます。 75 .RE 76 .PP 77 \fIoptions\fR 78 .RS 4 79 空白で区切られたコマンドライン・オプション。オプションを参照してください。 80 .RE 81 .PP 82 \fI@argfiles\fR 83 .RS 4 84 \fIjavadoc\fRコマンド・オプション、パッケージ名およびソース・ファイル名のリストを任意の順序で含むファイルの名前。 85 .RE 86 .SH "説明" 87 .PP 88 \fIjavadoc\fRコマンドは、一連のJavaソース・ファイルにある宣言およびドキュメンテーション・コメントを解析し、デフォルトでは、publicクラス、protectedクラス、ネストされたクラス(匿名の内部クラスは除く)、インタフェース、コンストラクタ、メソッド、およびフィールドについて記述した一連のHTMLページを生成します。\fIjavadoc\fRコマンドは、APIドキュメントの生成や、一連のソース・ファイルの実装ドキュメントの生成に使用できます。 89 .PP 90 \fIjavadoc\fRコマンドは、パッケージ全体、個々のソース・ファイル、またはその両方に対して実行できます。パッケージ全体のドキュメント化を行うには、\fI\-subpackages\fRオプションを使用してディレクトリおよびそのサブディレクトリを再帰的にたどるか、パッケージ名の明示的なリストを渡します。個々のソース・ファイルをドキュメント化するには、Javaソース・ファイル名のリストを渡します。簡単な例を参照してください。 91 .SS "ソース・ファイルの処理" 92 .PP 93 \fIjavadoc\fRコマンドは、ソースで終わるファイル、およびソース・ファイルで説明しているその他のファイルを処理します。個々のソース・ファイル名を渡して\fIjavadoc\fRを実行する場合、どのソース・ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソース・ファイル名を明示的に指定しなくても、\fIjavadoc\fRコマンドは3つの方法で実行できます。パッケージ名を渡し、\fI\-subpackages\fRオプションを使用するか、またはソース・ファイル名にワイルドカードを使用することができます。これらの場合、\fIjavadoc\fRコマンドがソース・ファイルの処理を行うのは、そのファイルが次のすべての要件を満たす場合のみです。 94 .sp 95 .RS 4 96 .ie n \{\ 97 \h'-04'\(bu\h'+03'\c 98 .\} 99 .el \{\ 100 .sp -1 101 .IP \(bu 2.3 102 .\} 103 ファイル名の接頭辞(\fI\&.java\fRを削除)が有効なクラス名である。 104 .RE 105 .sp 106 .RS 4 107 .ie n \{\ 108 \h'-04'\(bu\h'+03'\c 109 .\} 110 .el \{\ 111 .sp -1 112 .IP \(bu 2.3 113 .\} 114 ソース・ツリーのルートからの相対的なパス名が、区切り文字をドットに変換すると、有効なパッケージ名になる。 115 .RE 116 .sp 117 .RS 4 118 .ie n \{\ 119 \h'-04'\(bu\h'+03'\c 120 .\} 121 .el \{\ 122 .sp -1 123 .IP \(bu 2.3 124 .\} 125 パッケージ文に有効なパッケージ名が含まれている。 126 .RE 127 リンクの処理.PP 128 処理の実行中に、\fIjavadoc\fRコマンドは、その実行でドキュメント化されるパッケージ、クラス、およびメンバーの名前に対して、相互参照リンクを追加します。リンクは、次の場所に表示されます。@タグの説明については、javadocタグを参照してください。 129 .sp 130 .RS 4 131 .ie n \{\ 132 \h'-04'\(bu\h'+03'\c 133 .\} 134 .el \{\ 135 .sp -1 136 .IP \(bu 2.3 137 .\} 138 宣言(戻り値の型、引数の型、フィールドの型)。 139 .RE 140 .sp 141 .RS 4 142 .ie n \{\ 143 \h'-04'\(bu\h'+03'\c 144 .\} 145 .el \{\ 146 .sp -1 147 .IP \(bu 2.3 148 .\} 149 \fI@see\fRタグから生成された「\fI関連項目\fR」セクション。 150 .RE 151 .sp 152 .RS 4 153 .ie n \{\ 154 \h'-04'\(bu\h'+03'\c 155 .\} 156 .el \{\ 157 .sp -1 158 .IP \(bu 2.3 159 .\} 160 \fI{@link}\fRタグから生成されたインライン・テキスト。 161 .RE 162 .sp 163 .RS 4 164 .ie n \{\ 165 \h'-04'\(bu\h'+03'\c 166 .\} 167 .el \{\ 168 .sp -1 169 .IP \(bu 2.3 170 .\} 171 \fI@throws\fRタグから生成された例外の名前。 172 .RE 173 .sp 174 .RS 4 175 .ie n \{\ 176 \h'-04'\(bu\h'+03'\c 177 .\} 178 .el \{\ 179 .sp -1 180 .IP \(bu 2.3 181 .\} 182 インタフェースのメンバーに対する「\fI定義\fR」リンクと、クラスのメンバーに対する「\fIオーバーライド\fR」リンク。メソッド・コメントの継承を参照してください。 183 .RE 184 .sp 185 .RS 4 186 .ie n \{\ 187 \h'-04'\(bu\h'+03'\c 188 .\} 189 .el \{\ 190 .sp -1 191 .IP \(bu 2.3 192 .\} 193 パッケージ、クラス、およびメンバーをリストしているサマリー表。 194 .RE 195 .sp 196 .RS 4 197 .ie n \{\ 198 \h'-04'\(bu\h'+03'\c 199 .\} 200 .el \{\ 201 .sp -1 202 .IP \(bu 2.3 203 .\} 204 パッケージおよびクラスの継承ツリー。 205 .RE 206 .sp 207 .RS 4 208 .ie n \{\ 209 \h'-04'\(bu\h'+03'\c 210 .\} 211 .el \{\ 212 .sp -1 213 .IP \(bu 2.3 214 .\} 215 索引。 216 .RE 217 .PP 218 コマンドラインで指定しなかったクラスについての既存のテキスト(別に生成したテキスト)に対してリンクを追加するには、\fI\-link\fRおよび\fI\-linkoffline\fRオプションを利用できます。 219 処理の詳細.PP 220 \fIjavadoc\fRコマンドは実行するたびに1つの完全なドキュメントを生成します。前の実行の結果を変更または直接取り込む、増分ビルドを行いません。ただし、\fIjavadoc\fRコマンドは、他の実行の結果にリンクできます。 221 .PP 222 \fIjavadoc\fRコマンドの実装にはJavaコンパイラが必要で、Javaコンパイラに依存しています。\fIjavadoc\fRコマンドは\fIjavac\fRコマンドの一部を呼び出し、宣言をコンパイルして、メンバーの実装を無視します。\fIjavadoc\fRコマンドは、クラス階層を含むクラスの豊富な内部表現とクラスの「使用」関係を構築し、HTMLを生成します。さらに、J\fIjavadoc\fRコマンドは、ソース・コードのドキュメンテーション・コメントから、ユーザーの提供したドキュメントも取得します。ドキュメンテーション・コメントを参照してください。 223 .PP 224 \fIjavadoc\fRコマンドは、メソッド本体を持たない純粋なスタブ・ファイルであるソース・ファイルに対して実行できます。したがって、APIの実装前の設計の早い段階で、ドキュメンテーション・コメントを記述して\fIjavadoc\fRコメントを実行できます。 225 .PP 226 コンパイラに依存することによって、HTML出力は、実際の実装に正確に対応します。実際の実装は、明示的なソース・コードにではなく、暗黙のソース・コードに依存する場合があります。たとえば、\fIjavadoc\fRコマンドは、コンパイル済クラス・ファイルには存在するがソース・コードには存在しないデフォルト・コンストラクタをドキュメント化します。 227 .PP 228 多くの場合、\fIjavadoc\fRコマンドでは、ソース・ファイルのコードが不完全またはエラーを含んでいる場合でもドキュメントを生成できます。すべてのデバッグやトラブルシューティングを完了する前にドキュメントを生成できます。\fIjavadoc\fRコマンドはドキュメンテーション・コメントの基本的なチェックを行います。 229 .PP 230 \fIjavadoc\fRコマンドは、ドキュメントの内部構造を構築する際、参照クラスをすべてロードします。このため、 231 \fIjavadoc\fRコマンドは、ブートストラップ・クラス、拡張機能、またはユーザー・クラスにかかわらず、すべての参照クラスを検索できる必要があります。クラスの検出方法 232 (http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html)を参照してください 233 .PP 234 通常、作成するクラスは、拡張クラスとして、または\fIjavadoc\fRコマンドのクラス・パスでロードされる必要があります。 235 .SS "Javadocのドックレット" 236 .PP 237 \fIjavadoc\fRコマンドの出力の内容と形式は、ドックレットを使用してカスタマイズできます。\fIjavadoc\fRコマンドには、標準ドックレットと呼ばれるデフォルトの組込みドックレットがあります。標準ドックレットは、HTML形式のAPIドキュメントを生成します。標準ドックレットを修正またはサブクラスを作成することや、HTML、XML、MIF、RTFなどの好みの出力形式を生成する独自のドックレットを記述することも可能です。 238 .PP 239 \fI\-doclet\fRオプションでカスタム・ドックレットが指定されていない場合、\fIjavadoc\fRコマンドは、デフォルトの標準ドックレットを使用します。\fIjavadoc\fRコマンドには、使用されているドックレットに関係なく使用できるいくつかのオプションがあります。標準ドックレットでは、これらの他に、いくつかのコマンドライン・オプションが追加されます。オプションを参照してください。 240 .SH "ソース・ファイル" 241 .PP 242 \fIjavadoc\fRコマンドは、次のタイプのソース・ファイルから出力を生成します。そのファイルは、クラスのJava言語ソース・ファイル(\fI\&.java\fR)、パッケージ・コメント・ファイル、概要コメント・ファイル、およびその他の未処理のファイルです。ここでは、ドキュメント化しないがソース・ツリーに存在する場合があるテスト・ファイルやテンプレート・ファイルについても説明します。 243 .SS "クラスのソース・ファイル" 244 .PP 245 それぞれのクラスまたはインタフェース、およびそのメンバーは、独自のドキュメンテーション・コメントを持つことができ、それをソース・ファイル内に保持します。ドキュメンテーション・コメントを参照してください。 246 .SS "パッケージ・コメント・ファイル" 247 .PP 248 それぞれのパッケージは、独自のドキュメンテーション・コメントを持つことができ、それを専用のソース・ファイルに保持します。その内容は、\fIjavadoc\fRコマンドによって生成されるパッケージのサマリー・ページに組み込まれます。このコメントには、通常、そのパッケージ全体に当てはまるドキュメントを記述します。 249 .PP 250 パッケージ・コメント・ファイルを作成するには、次のいずれかのファイルにコメントを格納できます。 251 .sp 252 .RS 4 253 .ie n \{\ 254 \h'-04'\(bu\h'+03'\c 255 .\} 256 .el \{\ 257 .sp -1 258 .IP \(bu 2.3 259 .\} 260 \fIpackage\-info\&.java\fRファイルには、パッケージ宣言、パッケージ注釈、パッケージ・コメント、およびJavadocタグを格納できます。このファイルが優先されます。 261 .RE 262 .sp 263 .RS 4 264 .ie n \{\ 265 \h'-04'\(bu\h'+03'\c 266 .\} 267 .el \{\ 268 .sp -1 269 .IP \(bu 2.3 270 .\} 271 \fIpackage\&.html\fRファイルには、パッケージ・コメントとJavadocタグのみを格納できます。パッケージ注釈は格納できません。 272 .RE 273 .PP 274 各パッケージは、\fIpackage\&.html\fRファイルまたは\fIpackage\-info\&.java\fRファイルのいずれかを1つ持つことができますが、その両方を持つことはできません。このどちらかのファイルをソース・ファイルとともに、ソース・ツリー内のそのパッケージ・ディレクトリ内に配置してください。 275 package\-info\&.javaファイル.PP 276 \fIpackage\-info\&.java\fRファイルには、次の構造のパッケージ・コメントを含めることができます。コメントは、パッケージ宣言の前に配置されます。 277 .PP 278 \fB注意:\fR 279 コメント区切り文字である\fI/**\fRおよび\fI*/\fRが存在する必要がありますが、中間の行の先頭のアスタリスクは省略可能です。 280 .sp 281 .if n \{\ 282 .RS 4 283 .\} 284 .nf 285 /** 286 * Provides the classes necessary to create an 287 * applet and the classes an applet uses 288 * to communicate with its applet context\&. 289 * <p> 290 * The applet framework involves two entities: 291 * the applet and the applet context\&. 292 * An applet is an embeddable window (see the 293 * {@link java\&.awt\&.Panel} class) with a few extra 294 * methods that the applet context can use to 295 * initialize, start, and stop the applet\&. 296 * 297 * @since 1\&.0 298 * @see java\&.awt 299 */ 300 package java\&.lang\&.applet; 301 .fi 302 .if n \{\ 303 .RE 304 .\} 305 package\&.htmlファイル.PP 306 \fIpackage\&.html\fRファイルには、次の構造のパッケージ・コメントを含めることができます。コメントは、\fI<body>\fR要素に配置されます。 307 .PP 308 ファイル: 309 \fIjava/applet/package\&.html\fR 310 .sp 311 .if n \{\ 312 .RS 4 313 .\} 314 .nf 315 <HTML> 316 <BODY> 317 Provides the classes necessary to create an applet and the 318 classes an applet uses to communicate with its applet context\&. 319 <p> 320 The applet framework involves two entities: the applet 321 and the applet context\&. An applet is an embeddable 322 window (see the {@link java\&.awt\&.Panel} class) with a 323 few extra methods that the applet context can use to 324 initialize, start, and stop the applet\&. 325 326 @since 1\&.0 327 @see java\&.awt 328 </BODY> 329 </HTML> 330 .fi 331 .if n \{\ 332 .RE 333 .\} 334 .PP 335 \fIpackage\&.html\fRファイルは通常のHTMLファイルであり、パッケージ宣言を含んでいません。パッケージ・コメント・ファイルの内容はHTMLで記述しますが、例外が1つあります。このドキュメンテーション・コメントには、コメント区切り文字である\fI/**\fRと\fI*/\fR、または行頭のアスタリスクを含めない、という点です。コメントを書く場合は、最初の文をパッケージのサマリーとし、\fI<body>\fRタグと最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージ・タグを含めることができます。すべてのブロック・タグは、主説明の後に配置する必要があります。\fI@see\fRタグをパッケージ・コメント・ファイルに追加する場合には、完全修飾名を使用する必要があります。 336 コメント・ファイルの処理.PP 337 \fIjavadoc\fRコメントを実行すると、パッケージ・コメント・ファイルが検索されます。パッケージ・コメント・ファイルが見つかった場合は、\fIjavadoc\fRコマンドは次の手順を実行します。 338 .sp 339 .RS 4 340 .ie n \{\ 341 \h'-04'\(bu\h'+03'\c 342 .\} 343 .el \{\ 344 .sp -1 345 .IP \(bu 2.3 346 .\} 347 処理できるようにコメントをコピーします。package\&.htmlの場合、\fIjavadoc\fRコマンドは、\fI<body>\fRと\fI</body>\fR 348 HTMLタグ間のすべての内容をコピーします。\fI<head>\fRセクションを含め、そこに\fI<title>\fRタグやソース・ファイルの著作権記述などの情報を配置することもできますが、生成されたドキュメントにはそれらは一切表示されません。 349 .RE 350 .sp 351 .RS 4 352 .ie n \{\ 353 \h'-04'\(bu\h'+03'\c 354 .\} 355 .el \{\ 356 .sp -1 357 .IP \(bu 2.3 358 .\} 359 パッケージ・タグを処理します。パッケージ・タグを参照してください。 360 .RE 361 .sp 362 .RS 4 363 .ie n \{\ 364 \h'-04'\(bu\h'+03'\c 365 .\} 366 .el \{\ 367 .sp -1 368 .IP \(bu 2.3 369 .\} 370 処理したテキストを生成されたパッケージのサマリー・ページの下部に挿入します。Javaプラットフォーム、Standard Edition API仕様の概要 371 (http://docs\&.oracle\&.com/javase/8/docs/api/overview\-summary\&.html)を参照してください 372 .RE 373 .sp 374 .RS 4 375 .ie n \{\ 376 \h'-04'\(bu\h'+03'\c 377 .\} 378 .el \{\ 379 .sp -1 380 .IP \(bu 2.3 381 .\} 382 パッケージのサマリー・ページの先頭に、パッケージ・コメントの最初の文をコピーします。さらに、\fIjavadoc\fRコマンドは、概要ページのパッケージ・リストに、パッケージ名とパッケージ・コメントの最初の文を追加します。Javaプラットフォーム、Standard Edition API仕様の概要 383 (http://docs\&.oracle\&.com/javase/8/docs/api/overview\-summary\&.html)を参照してください 384 .sp 385 文の終わりは、クラスやメンバーの主説明の最初の文の終わりと同じルールによって判断されます。 386 .RE 387 .SS "概要コメント・ファイル" 388 .PP 389 ドキュメント化する各アプリケーションまたはパッケージ・セットは、独自の概要ドキュメンテーション・コメントを持つことができ、それは専用のソース・ファイルに保持されます。その内容は、\fIjavadoc\fRコマンドによって生成される概要ページに組み込まれます。このコメントには、通常、アプリケーションまたはパッケージ・セット全体に当てはまるドキュメントを記述します。 390 .PP 391 このファイルにはoverview\&.htmlなどの名前を付けることができ、どこに配置してもかまいません。一般的な場所は、ソース・ツリーの最上部です。 392 .PP 393 たとえば、\fIjava\&.applet\fRパッケージのソース・ファイルが/home/user/src/java/appletディレクトリに格納されている場合、概要コメント・ファイルは/home/user/src/overview\&.htmlに作成できます。 394 .PP 395 異なるパッケージのセットに対して\fIjavadoc\fRコマンドを複数回実行する場合は、同じ1つのソース・ファイルのセットに対して複数の概要コメント・ファイルを作成できます。たとえば、内部ドキュメント用に\fI\-private\fRを指定して\fIjavadoc\fRコマンドを1回実行した後、公開ドキュメント用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメント・ファイルの1文目で、そのドキュメントを公開用または内部用として記述できます。 396 .PP 397 概要コメント・ファイルの内容は、HTMLで記述された1つの大きなドキュメンテーション・コメントです。最初の文はアプリケーションまたはパッケージのセットのサマリーとします。\fI<body>\fRタグと最初の文の間にタイトルやその他のテキストを含めないようにします。{\fI@link}\fRなどのインライン・タグを除くすべてのタグは、主説明の後に配置する必要があります。\fI@see\fRタグを追加する場合には、完全修飾名を使用する必要があります。 398 .PP 399 \fIjavadoc\fRコマンドの実行時に、\fI\-overview\fRオプションを使用して概要コメント・ファイル名を指定します。このファイルは、パッケージ・コメント・ファイルと同じように処理されます。\fIjavadoc\fRコマンドは次の手順を実行します。 400 .sp 401 .RS 4 402 .ie n \{\ 403 \h'-04'\(bu\h'+03'\c 404 .\} 405 .el \{\ 406 .sp -1 407 .IP \(bu 2.3 408 .\} 409 \fI<body>\fRと\fI</body>\fRタグの間にある内容をすべて処理対象としてコピーします。 410 .RE 411 .sp 412 .RS 4 413 .ie n \{\ 414 \h'-04'\(bu\h'+03'\c 415 .\} 416 .el \{\ 417 .sp -1 418 .IP \(bu 2.3 419 .\} 420 概要タグがあれば処理します。概要タグを参照してください。 421 .RE 422 .sp 423 .RS 4 424 .ie n \{\ 425 \h'-04'\(bu\h'+03'\c 426 .\} 427 .el \{\ 428 .sp -1 429 .IP \(bu 2.3 430 .\} 431 処理したテキストを生成された概要ページの下部に挿入します。JavaプラットフォームStandard Edition API仕様の概要 432 (http://docs\&.oracle\&.com/javase/8/docs/api/overview\-summary\&.html)を参照してください 433 .RE 434 .sp 435 .RS 4 436 .ie n \{\ 437 \h'-04'\(bu\h'+03'\c 438 .\} 439 .el \{\ 440 .sp -1 441 .IP \(bu 2.3 442 .\} 443 概要サマリー・ページの先頭に、概要コメントの最初の文をコピーします。 444 .RE 445 .SS "未処理のファイル" 446 .PP 447 ソース・ファイルには、\fIjavadoc\fRコマンドによって宛先ディレクトリにコピーされる、任意のファイルを含めることができます。このようなファイルには、通常、グラフィック・ファイル、サンプルのJavaソースおよびクラス・ファイル、一般的なJavaソース・ファイルのドキュメンテーション・コメントの影響を受けない多くの内容を含む独立したHTMLファイルなどがあります。 448 .PP 449 未処理のファイルを含めるには、doc\-filesというディレクトリにファイルを配置します。doc\-filesディレクトリは、ソース・ファイルを含む任意のパッケージ・ディレクトリのサブディレクトリになることができます。doc\-filesサブディレクトリは、パッケージごとに1つ用意できます。 450 .PP 451 たとえば、ボタンのイメージを\fIjava\&.awt\&.Button\fRクラスのドキュメントに含める場合には、そのイメージ・ファイルを/home/user/src/java/awt/doc\-files/ディレクトリに置きます。doc\-filesディレクトリを/home/user/src/java/doc\-filesに置かないでください。javaはパッケージではないからです。ソース・ファイルを含めることもできません。 452 .PP 453 \fIjavadoc\fRコマンドはファイルを参照しないので、未処理のファイルへのすべてのリンクは、コードに含まれている必要があります。\fIjavadoc\fRコマンドはディレクトリとそのすべての内容を宛先にコピーします。次の例では、Button\&.javaドキュメンテーション・コメントのリンクがどのように見えるかを示しています。 454 .sp 455 .if n \{\ 456 .RS 4 457 .\} 458 .nf 459 /** 460 * This button looks like this: 461 * <img src="doc\-files/Button\&.gif"> 462 */ 463 .fi 464 .if n \{\ 465 .RE 466 .\} 467 .SS "テストおよびテンプレート・ファイル" 468 .PP 469 ソース・ツリーのテストおよびテンプレート・ファイルを、ソース・ファイルが存在するディレクトリまたはサブディレクトリと同じディレクトリに格納できます。テストおよびテンプレート・ファイルが処理されるのを防ぐには、\fIjavadoc\fRコマンドを実行し、明示的に個別のソース・ファイル名を渡します。 470 .PP 471 テスト・ファイルは、有効な、コンパイル可能なソース・ファイルです。テンプレート・ファイルは、有効な、互換性のあるソース・ファイルではありませんが、多くの場合、\fI\&.java\fR接尾辞を持っています。 472 テスト・ファイル.PP 473 テスト・ファイルを、名前なしパッケージや、ソース・ファイルが存在するパッケージとは別のパッケージに属するようにする場合、テスト・ファイルをソース・ファイルの下のサブディレクトリに配置し、そのディレクトリに無効な名前を付けます。テスト・ファイルをソースと同じディレクトリに配置し、パッケージ名を示すコマンドライン引数を指定して\fIjavadoc\fRコマンドを呼び出すと、テスト・ファイルは警告またはエラーを引き起こします。ファイルが無効な名前を持つサブディレクトリ内に存在する場合、テスト・ファイル・ディレクトリはスキップされ、エラーまたは警告は発行されません。たとえば、ソース・ファイルのテスト・ファイルをcom\&.package1に追加するには、無効なパッケージ名のサブディレクトリに配置します。次のディレクトリ名にはハイフンが含まれているため無効です。 474 .sp 475 .if n \{\ 476 .RS 4 477 .\} 478 .nf 479 com/package1/test\-files/ 480 .fi 481 .if n \{\ 482 .RE 483 .\} 484 .PP 485 テスト・ファイルにドキュメンテーション・コメントが含まれる場合、\fIjavadoc\fRコマンドの個別の実行で、ワイルドカードを含んだテスト・ソース・ファイル名(\fIcom/package1/test\-files/*\&.java\fRなど)を渡して、テスト・ファイルのドキュメントを生成するように設定できます。 486 テンプレート・ファイル.PP 487 テンプレート・ファイルをソース・ディレクトリに配置するが、\fIjavadoc\fRコマンドを実行するときにエラーを生成しない場合、ファイルに\fIBuffer\-Template\&.java\fRなどの無効な名前を付けて、処理させないようにします。\fIjavadoc\fRコマンドは、接尾辞の\fI\&.java\fRが削除されると有効なクラス名になる名前を持つソース・ファイルのみを処理します。 488 .SH "生成されるファイル" 489 .PP 490 デフォルトでは、\fIjavadoc\fRコマンドは、HTML形式のドキュメントを生成する標準ドックレットを使用します。標準ドックレットは、ここで説明する、基本内容ページ、相互参照ページ、サポート・ページを生成します。各HTMLページは個別のファイルに対応します。\fIjavadoc\fRコマンドは、2つのタイプのファイルを生成します。最初のタイプには、クラスおよびインタフェースに応じた名前が付けられます。2番目のタイプには、最初のタイプのファイルとの競合を防ぐために、ハイフンが含まれます(package\-summary\&.htmlなど)。 491 .SS "基本内容ページ" 492 .sp 493 .RS 4 494 .ie n \{\ 495 \h'-04'\(bu\h'+03'\c 496 .\} 497 .el \{\ 498 .sp -1 499 .IP \(bu 2.3 500 .\} 501 記載されているクラスまたはインタフェースごとに1つのクラスまたはインタフェース・ページ(classname\&.html)。 502 .RE 503 .sp 504 .RS 4 505 .ie n \{\ 506 \h'-04'\(bu\h'+03'\c 507 .\} 508 .el \{\ 509 .sp -1 510 .IP \(bu 2.3 511 .\} 512 記載されているパッケージごとに1つのパッケージ・ページ(package\-summary\&.html)。\fIjavadoc\fRコマンドは、ソース・ツリーのパッケージ・ディレクトリ内にあるpackage\&.htmlまたはpackage\-info\&.javaという名前のファイル内のHTMLテキストをすべて組み入れます。 513 .RE 514 .sp 515 .RS 4 516 .ie n \{\ 517 \h'-04'\(bu\h'+03'\c 518 .\} 519 .el \{\ 520 .sp -1 521 .IP \(bu 2.3 522 .\} 523 パッケージのセット全体に対して1つの概要ページ(overview\-summary\&.html)。概要ページは、生成ドキュメントの先頭ページになります。\fIjavadoc\fRコマンドは、\fI\-overview\fRオプションで指定されたファイル内のHTMLテキストをすべて組み入れます。概要ページが作成されるのは、\fIjavadoc\fRコマンドに複数のパッケージ名を渡した場合のみです。HTMLフレームおよびオプションを参照してください。 524 .RE 525 .SS "相互参照ページ" 526 .sp 527 .RS 4 528 .ie n \{\ 529 \h'-04'\(bu\h'+03'\c 530 .\} 531 .el \{\ 532 .sp -1 533 .IP \(bu 2.3 534 .\} 535 パッケージのセット全体に対して1つのクラス階層ページ(overview\-tree\&.html)。階層ページを表示するには、ナビゲーション・バーの「概要」をクリックしてから、「階層ツリー」をクリックします。 536 .RE 537 .sp 538 .RS 4 539 .ie n \{\ 540 \h'-04'\(bu\h'+03'\c 541 .\} 542 .el \{\ 543 .sp -1 544 .IP \(bu 2.3 545 .\} 546 パッケージごとに1つのクラス階層ページ(package\-tree\&.html)。階層ページを表示するには、特定のパッケージ、クラス、またはインタフェースのページに移動し、「階層ツリー」をクリックしてそのパッケージの階層を表示します。 547 .RE 548 .sp 549 .RS 4 550 .ie n \{\ 551 \h'-04'\(bu\h'+03'\c 552 .\} 553 .el \{\ 554 .sp -1 555 .IP \(bu 2.3 556 .\} 557 パッケージごとに1つの使用ページ(package\-use\&.html)と、クラスおよびインタフェースごとに1つずつの使用ページ(class\-use/classname\&.html)。使用ページでは、指定したクラス、インタフェース、またはパッケージの一部を使用しているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドについて記述されます。たとえば、クラスまたはインタフェースAを例にすると、その使用ページには、Aのサブクラス、Aとして宣言されたフィールド、Aを返すメソッド、A型のパラメータを持つメソッドおよびコンストラクタが組み込まれます。使用ページを表示するには、パッケージ、クラス、またはインタフェースに移動し、ナビゲーション・バーの「使用」リンクをクリックします。 558 .RE 559 .sp 560 .RS 4 561 .ie n \{\ 562 \h'-04'\(bu\h'+03'\c 563 .\} 564 .el \{\ 565 .sp -1 566 .IP \(bu 2.3 567 .\} 568 すべての非推奨APIとその推奨する代替をリストする非推奨APIページ(deprecated\-list\&.html)。非推奨APIは将来の実装で削除される可能性があるので使用しないでください。 569 .RE 570 .sp 571 .RS 4 572 .ie n \{\ 573 \h'-04'\(bu\h'+03'\c 574 .\} 575 .el \{\ 576 .sp -1 577 .IP \(bu 2.3 578 .\} 579 定数フィールドの値用の定数フィールド値ページ(constant\-values\&.html)。 580 .RE 581 .sp 582 .RS 4 583 .ie n \{\ 584 \h'-04'\(bu\h'+03'\c 585 .\} 586 .el \{\ 587 .sp -1 588 .IP \(bu 2.3 589 .\} 590 直列化された形式ページ(serialized\-form\&.html)。フィールドおよびメソッドの説明を含む、直列化可能かつ外部化可能なクラスに関する情報用のページです。このページ内の情報は、APIを使用する開発者ではなく、再実装者に必要な情報です。直列化された形式ページへアクセスするには、直列化されたクラスに移動して、そのクラス・コメントにある「関連項目」セクションで「直列化された形式」をクリックします。標準ドックレットは直列化された形式ページを生成します。このページには、Serializableを実装するすべてのクラス(publicまたは非public)が、その\fIreadObject\fRや\fIwriteObject\fRメソッド、直列化されたフィールド、および\fI@serial\fR、\fI@serialField\fR、\fI@serialData\fRタグからのドキュメンテーション・コメントとともにリストされます。直列化可能なpublicクラスを除外するには、そのクラス(またはそのパッケージ)を\fI@serial\fR 591 excludeでマークします。直列化可能なpackage\-privateクラスを含めるには、そのクラス(またはそのパッケージ)を\fI@serial\fR 592 includeでマークします。リリース1\&.4では、\fI\-private\fRオプションを指定せずに\fIjavadoc\fRコマンドを実行することにより、publicクラスおよびprivateクラスの完全に直列化された形式を生成できます。オプションを参照してください。 593 .RE 594 .sp 595 .RS 4 596 .ie n \{\ 597 \h'-04'\(bu\h'+03'\c 598 .\} 599 .el \{\ 600 .sp -1 601 .IP \(bu 2.3 602 .\} 603 索引ページ(\fIindex\-*\&.html\fR)。すべてのクラス名、インタフェース名、コンストラクタ名、フィールド名、およびメソッド名がアルファベット順に並んでいます。索引ページは、Unicodeを扱えるように国際化されています。1つのファイルとして生成することも、先頭文字(英語の場合A\(enZ)ごとに別々のファイルとして生成することもできます。 604 .RE 605 .SS "サポート・ページ" 606 .sp 607 .RS 4 608 .ie n \{\ 609 \h'-04'\(bu\h'+03'\c 610 .\} 611 .el \{\ 612 .sp -1 613 .IP \(bu 2.3 614 .\} 615 ヘルプ・ページ(help\-doc\&.html)。ナビゲーション・バーや前述の各ページに関する説明が記載されています。デフォルトのヘルプ・ファイルを独自のカスタム・ヘルプ・ファイルでオーバーライドするには、\fI\-helpfile\fRを使用します。 616 .RE 617 .sp 618 .RS 4 619 .ie n \{\ 620 \h'-04'\(bu\h'+03'\c 621 .\} 622 .el \{\ 623 .sp -1 624 .IP \(bu 2.3 625 .\} 626 表示用のHTMLフレームを作成する1つのindex\&.htmlファイル。フレーム付きの先頭ページを表示するにはこのファイルをロードします。index\&.htmlファイルには、テキスト・コンテンツは含まれていません。 627 .RE 628 .sp 629 .RS 4 630 .ie n \{\ 631 \h'-04'\(bu\h'+03'\c 632 .\} 633 .el \{\ 634 .sp -1 635 .IP \(bu 2.3 636 .\} 637 複数のフレーム・ファイル(\fI*\-frame\&.html\fR)。パッケージ、クラス、およびインタフェースのリストが含まれています。フレーム・ファイルはHTMLフレームを表示します。 638 .RE 639 .sp 640 .RS 4 641 .ie n \{\ 642 \h'-04'\(bu\h'+03'\c 643 .\} 644 .el \{\ 645 .sp -1 646 .IP \(bu 2.3 647 .\} 648 パッケージ・リスト・ファイル(package\-list)。\fI\-link\fRおよび\fI\-linkoffline\fRオプションで使用されます。パッケージ・リスト・ファイルはテキスト・ファイルであり、どのリンクからもアクセスできません。 649 .RE 650 .sp 651 .RS 4 652 .ie n \{\ 653 \h'-04'\(bu\h'+03'\c 654 .\} 655 .el \{\ 656 .sp -1 657 .IP \(bu 2.3 658 .\} 659 スタイルシート・ファイル(stylesheet\&.css)。生成されるページの一部の要素について色、フォント・ファミリ、フォント・サイズ、フォント・スタイル、および配置を制御します。 660 .RE 661 .sp 662 .RS 4 663 .ie n \{\ 664 \h'-04'\(bu\h'+03'\c 665 .\} 666 .el \{\ 667 .sp -1 668 .IP \(bu 2.3 669 .\} 670 doc\-filesディレクトリ。宛先ディレクトリにコピーするイメージ、サンプル・コード、ソース・コードなどのファイルが格納されます。これらのファイルは、\fIjavadoc\fRコマンドによって処理されません。このディレクトリは、ソース・ツリーの中に存在する場合にのみ処理されます。 671 .RE 672 .PP 673 オプションを参照してください。 674 .SS "HTMLフレーム" 675 .PP 676 \fIjavadoc\fRコマンドは、コマンドに渡された値に基づき、最小限必要な数(2または3)のフレームを生成します。\fIjavadoc\fRコマンドに引数として1つのパッケージ名または1つのパッケージに含まれるソース・ファイルを渡す場合は、パッケージのリストが省略されます。そのかわりに、\fIjavadoc\fRコマンドは左側の列に1つのフレームを作成し、クラスのリストを表示します。複数のパッケージ名を渡した場合は、\fIjavadoc\fRコマンドは、すべてのパッケージをリストする第3のフレームと概要ページ(overview\-summary\&.html)を作成します。フレームを省略するには、「フレームなし」リンクをクリックするか、overview\-summary\&.htmlページからページ・セットを表示します。 677 .SS "生成されるファイルの構造" 678 .PP 679 生成されるクラス・ファイルおよびインタフェース・ファイルは、Javaソース・ファイルおよびクラス・ファイルと同じディレクトリ階層に編成されます。1つのサブパッケージにつき1つのディレクトリ、という構造になります。 680 .PP 681 たとえば、\fIjava\&.applet\&.Applet\fRクラス用に生成されるドキュメントは、java/applet/Applet\&.htmlに格納されます。 682 .PP 683 生成先ディレクトリの名前が\fIapidocs\fRだとすると、\fIjava\&.applet\fRパッケージのファイルの構造は、次のとおりです。前述のように、\fIframe\fRという語を名前に含むファイルは、すべて左上または左下のフレームに表示されます。それ以外のHTMLファイルは、すべて右側のフレームに表示されます。 684 .PP 685 ディレクトリは太字です。アスタリスク(*)は、\fIjavadoc\fRコマンドへの引数がパッケージ名ではなくソース・ファイル名である場合に省略されるファイルおよびディレクトリを示しています。引数がソース・ファイル名の場合、空のパッケージ・リストが作成されます。doc\-filesディレクトリは、ソース・ツリー内に存在する場合にのみ、生成先に作成されます。生成されるファイルを参照してください。 686 .sp 687 .RS 4 688 .ie n \{\ 689 \h'-04'\(bu\h'+03'\c 690 .\} 691 .el \{\ 692 .sp -1 693 .IP \(bu 2.3 694 .\} 695 \fBapidocs\fR: 最上位レベル・ディレクトリ 696 .sp 697 .RS 4 698 .ie n \{\ 699 \h'-04'\(bu\h'+03'\c 700 .\} 701 .el \{\ 702 .sp -1 703 .IP \(bu 2.3 704 .\} 705 index\&.html: HTMLフレームを設定する初期ページ 706 .RE 707 .sp 708 .RS 4 709 .ie n \{\ 710 \h'-04'\(bu\h'+03'\c 711 .\} 712 .el \{\ 713 .sp -1 714 .IP \(bu 2.3 715 .\} 716 *overview\-summary\&.html: パッケージ・リストとサマリー 717 .RE 718 .sp 719 .RS 4 720 .ie n \{\ 721 \h'-04'\(bu\h'+03'\c 722 .\} 723 .el \{\ 724 .sp -1 725 .IP \(bu 2.3 726 .\} 727 overview\-tree\&.html: すべてのパッケージのクラス階層 728 .RE 729 .sp 730 .RS 4 731 .ie n \{\ 732 \h'-04'\(bu\h'+03'\c 733 .\} 734 .el \{\ 735 .sp -1 736 .IP \(bu 2.3 737 .\} 738 deprecated\-list\&.html: すべてのパッケージの非推奨API 739 .RE 740 .sp 741 .RS 4 742 .ie n \{\ 743 \h'-04'\(bu\h'+03'\c 744 .\} 745 .el \{\ 746 .sp -1 747 .IP \(bu 2.3 748 .\} 749 constant\-values\&.html: すべてのパッケージの静的フィールド値 750 .RE 751 .sp 752 .RS 4 753 .ie n \{\ 754 \h'-04'\(bu\h'+03'\c 755 .\} 756 .el \{\ 757 .sp -1 758 .IP \(bu 2.3 759 .\} 760 serialized\-form\&.html: すべてのパッケージの直列化されたフォーム 761 .RE 762 .sp 763 .RS 4 764 .ie n \{\ 765 \h'-04'\(bu\h'+03'\c 766 .\} 767 .el \{\ 768 .sp -1 769 .IP \(bu 2.3 770 .\} 771 *overview\-frame\&.html: 左上のフレームに表示するすべてのパッケージ 772 .RE 773 .sp 774 .RS 4 775 .ie n \{\ 776 \h'-04'\(bu\h'+03'\c 777 .\} 778 .el \{\ 779 .sp -1 780 .IP \(bu 2.3 781 .\} 782 allclasses\-frame\&.html: 左下のフレームに表示するすべてのクラス 783 .RE 784 .sp 785 .RS 4 786 .ie n \{\ 787 \h'-04'\(bu\h'+03'\c 788 .\} 789 .el \{\ 790 .sp -1 791 .IP \(bu 2.3 792 .\} 793 help\-doc\&.html: Javadocページの編成に関するヘルプ 794 .RE 795 .sp 796 .RS 4 797 .ie n \{\ 798 \h'-04'\(bu\h'+03'\c 799 .\} 800 .el \{\ 801 .sp -1 802 .IP \(bu 2.3 803 .\} 804 index\-all\&.html: 805 \fI\-splitindex\fRオプションなしで作成されたデフォルトの索引 806 .RE 807 .sp 808 .RS 4 809 .ie n \{\ 810 \h'-04'\(bu\h'+03'\c 811 .\} 812 .el \{\ 813 .sp -1 814 .IP \(bu 2.3 815 .\} 816 \fBindex\-files\fR: 817 \fI\-splitindex\fRオプションを指定して作成されたディレクトリ 818 .sp 819 .RS 4 820 .ie n \{\ 821 \h'-04'\(bu\h'+03'\c 822 .\} 823 .el \{\ 824 .sp -1 825 .IP \(bu 2.3 826 .\} 827 index\-<number>\&.html: 828 \fI\-splitindex\fRオプションを指定して作成された索引ファイル 829 .RE 830 .RE 831 .sp 832 .RS 4 833 .ie n \{\ 834 \h'-04'\(bu\h'+03'\c 835 .\} 836 .el \{\ 837 .sp -1 838 .IP \(bu 2.3 839 .\} 840 package\-list: 外部参照を解決するためのパッケージ名 841 .RE 842 .sp 843 .RS 4 844 .ie n \{\ 845 \h'-04'\(bu\h'+03'\c 846 .\} 847 .el \{\ 848 .sp -1 849 .IP \(bu 2.3 850 .\} 851 stylesheet\&.css: フォント、色、位置などを定義します 852 .RE 853 .RE 854 .sp 855 .RS 4 856 .ie n \{\ 857 \h'-04'\(bu\h'+03'\c 858 .\} 859 .el \{\ 860 .sp -1 861 .IP \(bu 2.3 862 .\} 863 \fBjava\fR: パッケージ・ディレクトリ 864 .sp 865 .RS 4 866 .ie n \{\ 867 \h'-04'\(bu\h'+03'\c 868 .\} 869 .el \{\ 870 .sp -1 871 .IP \(bu 2.3 872 .\} 873 \fBapplet\fR: サブパッケージ・ディレクトリ 874 .sp 875 .RS 4 876 .ie n \{\ 877 \h'-04'\(bu\h'+03'\c 878 .\} 879 .el \{\ 880 .sp -1 881 .IP \(bu 2.3 882 .\} 883 Applet\&.html: 884 \fIApplet\fRクラス・ページ 885 .RE 886 .sp 887 .RS 4 888 .ie n \{\ 889 \h'-04'\(bu\h'+03'\c 890 .\} 891 .el \{\ 892 .sp -1 893 .IP \(bu 2.3 894 .\} 895 AppletContext\&.html: 896 \fIAppletContext\fRインタフェース 897 .RE 898 .sp 899 .RS 4 900 .ie n \{\ 901 \h'-04'\(bu\h'+03'\c 902 .\} 903 .el \{\ 904 .sp -1 905 .IP \(bu 2.3 906 .\} 907 AppletStub\&.html: 908 \fIAppletStub\fRインタフェース 909 .RE 910 .sp 911 .RS 4 912 .ie n \{\ 913 \h'-04'\(bu\h'+03'\c 914 .\} 915 .el \{\ 916 .sp -1 917 .IP \(bu 2.3 918 .\} 919 AudioClip\&.html: 920 \fIAudioClip\fRインタフェース 921 .RE 922 .sp 923 .RS 4 924 .ie n \{\ 925 \h'-04'\(bu\h'+03'\c 926 .\} 927 .el \{\ 928 .sp -1 929 .IP \(bu 2.3 930 .\} 931 package\-summary\&.html: クラスとサマリー 932 .RE 933 .sp 934 .RS 4 935 .ie n \{\ 936 \h'-04'\(bu\h'+03'\c 937 .\} 938 .el \{\ 939 .sp -1 940 .IP \(bu 2.3 941 .\} 942 package\-frame\&.html: 左下のフレームに表示するパッケージ・クラス 943 .RE 944 .sp 945 .RS 4 946 .ie n \{\ 947 \h'-04'\(bu\h'+03'\c 948 .\} 949 .el \{\ 950 .sp -1 951 .IP \(bu 2.3 952 .\} 953 package\-tree\&.html: このパッケージのクラス階層 954 .RE 955 .sp 956 .RS 4 957 .ie n \{\ 958 \h'-04'\(bu\h'+03'\c 959 .\} 960 .el \{\ 961 .sp -1 962 .IP \(bu 2.3 963 .\} 964 package\-use\&.html: このパッケージが使用される場所 965 .RE 966 .sp 967 .RS 4 968 .ie n \{\ 969 \h'-04'\(bu\h'+03'\c 970 .\} 971 .el \{\ 972 .sp -1 973 .IP \(bu 2.3 974 .\} 975 \fBdoc\-files\fR: イメージおよびサンプル・ファイルのディレクトリ 976 .RE 977 .sp 978 .RS 4 979 .ie n \{\ 980 \h'-04'\(bu\h'+03'\c 981 .\} 982 .el \{\ 983 .sp -1 984 .IP \(bu 2.3 985 .\} 986 \fBclass\-use\fR: イメージおよびサンプル・ファイルの場所 987 .sp 988 \- Applet\&.html: Appletクラスの使用 989 .sp 990 \- AppletContext\&.html: 991 \fIAppletContext\fRインタフェースの使用 992 .sp 993 \- AppletStub\&.html: 994 \fIAppletStub\fRインタフェースの使用 995 .sp 996 \- AudioClip\&.html: 997 \fIAudioClip\fRインタフェースの使用 998 .RE 999 .RE 1000 .RE 1001 .sp 1002 .RS 4 1003 .ie n \{\ 1004 \h'-04'\(bu\h'+03'\c 1005 .\} 1006 .el \{\ 1007 .sp -1 1008 .IP \(bu 2.3 1009 .\} 1010 \fBsrc\-html\fR: ソース・コード・ディレクトリ 1011 .sp 1012 .RS 4 1013 .ie n \{\ 1014 \h'-04'\(bu\h'+03'\c 1015 .\} 1016 .el \{\ 1017 .sp -1 1018 .IP \(bu 2.3 1019 .\} 1020 \fBjava\fR: パッケージ・ディレクトリ 1021 .sp 1022 .RS 4 1023 .ie n \{\ 1024 \h'-04'\(bu\h'+03'\c 1025 .\} 1026 .el \{\ 1027 .sp -1 1028 .IP \(bu 2.3 1029 .\} 1030 \fBapplet\fR: サブパッケージ・ディレクトリ 1031 .sp 1032 \- Applet\&.html: Appletソース・コード 1033 .sp 1034 \- AppletContext\&.html: 1035 \fIAppletContext\fRソース・コード 1036 .sp 1037 \- AppletStub\&.html: 1038 \fIAppletStub\fRソース・コード 1039 .sp 1040 \- AudioClip\&.html: 1041 \fIAudioClip\fRソース・コード 1042 .RE 1043 .RE 1044 .RE 1045 .SS "生成されるAPI宣言" 1046 .PP 1047 \fIjavadoc\fRコマンドは、それぞれのクラス、インタフェース、フィールド、コンストラクタ、およびメソッドの記述の最初に、そのAPI用の宣言を生成します。たとえば、\fIBoolean\fRクラスの宣言は、次のようになります。 1048 .sp 1049 .if n \{\ 1050 .RS 4 1051 .\} 1052 .nf 1053 public final class Boolean 1054 extends Object 1055 implements Serializable 1056 .fi 1057 .if n \{\ 1058 .RE 1059 .\} 1060 .PP 1061 \fIBoolean\&.valueOf\fRメソッドの宣言は次のとおりです。 1062 .sp 1063 .if n \{\ 1064 .RS 4 1065 .\} 1066 .nf 1067 public static Boolean valueOf(String s) 1068 .fi 1069 .if n \{\ 1070 .RE 1071 .\} 1072 .PP 1073 \fIjavadoc\fRコマンドは、修飾子\fIpublic\fR、\fIprotected\fR、\fIprivate\fR、\fIabstract\fR、\fIfinal\fR、\fIstatic\fR、\fItransient\fR、および\fIvolatile\fRを含めることができますが、\fIsynchronized\fRおよび\fInative\fRはできません。\fIsynchronized\fRおよび\fInative\fR修飾子は、実装の詳細とみなされているため、API仕様には含まれません。 1074 .PP 1075 APIでは、並行性セマンティクスについて、キーワード\fIsynchronized\fRに依存するのではなく、コメントの主説明としてドキュメント化する必要があります。たとえば、「1つのenumerationを複数のスレッドから並行して使用することはできない」のように記述します。ドキュメントには、これらのセマンティクスを実現する方法を記述しないでください。たとえば、\fIHashtable\fRオプションはスレッドセーフである必要がありますが、「エクスポートされるすべてのメソッドを同期化してそれを実現する」のように指定する根拠はありません。より高度な並行性のために、バケット・レベルで内部的に同期化する権限を保有しておくことをお薦めします。 1076 .SH "ドキュメンテーション・コメント" 1077 .PP 1078 このセクションでは、ソース・コードのコメントとコメントの継承について説明します。 1079 .SS "ソース・コード・コメント" 1080 .PP 1081 ソース・コードの任意のクラス、インタフェース、メソッド、コンストラクタ、またはフィールドの宣言の前に、ドキュメンテーション・コメントを記述することができます。各パッケージにもドキュメンテーション・コメントを作成できます。構文は若干異なりますが、概要にもドキュメンテーション・コメントを作成できます。ドキュメンテーション・コメントは、\fI/**\fRと、終わりを表す\fI*/\fRの間にある文字から構成されます。先頭のアスタリスクは各行で使用でき、次の項で詳しく説明します。コメントのテキストは、複数行にわたって記述できます。 1082 .sp 1083 .if n \{\ 1084 .RS 4 1085 .\} 1086 .nf 1087 /** 1088 * This is the typical format of a simple documentation comment 1089 * that spans two lines\&. 1090 */ 1091 .fi 1092 .if n \{\ 1093 .RE 1094 .\} 1095 .PP 1096 スペースを節約するには、コメントを1行に入れます。 1097 .sp 1098 .if n \{\ 1099 .RS 4 1100 .\} 1101 .nf 1102 /** This comment takes up only one line\&. */ 1103 .fi 1104 .if n \{\ 1105 .RE 1106 .\} 1107 コメントの配置.PP 1108 ドキュメンテーション・コメントは、クラス、インタフェース、コンストラクタ、メソッド、またはフィールド宣言の直前に配置される場合にのみ認識されます。メソッドの本体に置かれているドキュメンテーション・コメントは無視されます。\fIjavadoc\fRコマンドは、宣言文ごとに1つのドキュメンテーション・コメントしか認識しません。タグを使用できる場所を参照してください。 1109 .PP 1110 よくある間違いは、クラス・コメントとクラス宣言の間に\fIimport\fR文を置いてしまうことです。\fIjavadoc\fRコマンドはクラス・コメントを無視するので、\fIimport\fR文をこの場所に配置しないでください。 1111 .sp 1112 .if n \{\ 1113 .RS 4 1114 .\} 1115 .nf 1116 /** 1117 * This is the class comment for the class Whatever\&. 1118 */ 1119 1120 import com\&.example; // MISTAKE \- Important not to put import statement here 1121 1122 public class Whatever{ } 1123 .fi 1124 .if n \{\ 1125 .RE 1126 .\} 1127 コメントのパーツ.PP 1128 ドキュメンテーション・コメントには、主説明とその後に続くタグ・セクションが含まれます。主説明は、開始区切り文字\fI/**\fRで始まり、タグ・セクションまで続きます。タグ・セクションは、先頭文字が\fI@\fRの行で定義される最初のブロック・タグから始まります(先頭のアスタリスク、空白文字、先頭の区切り文字\fI/**\fRは除く)。主説明を記述せず、タグ・セクションのみのコメントを記述することもできます。主説明は、タグ・セクション以降に続けることはできません。タグの引数は、複数行にわたって記述できます。タグの数に制限はありません。何回も記述できるタグと、1回しか記述できないタグがあります。たとえば、次の\fI@see\fRタグからタグ・セクションは始まります。 1129 .sp 1130 .if n \{\ 1131 .RS 4 1132 .\} 1133 .nf 1134 /** 1135 * This sentence holds the main description for this documentation comment\&. 1136 * @see java\&.lang\&.Object 1137 */ 1138 .fi 1139 .if n \{\ 1140 .RE 1141 .\} 1142 ブロックおよびインライン・タグ.PP 1143 タグは、\fIjavadoc\fRコマンドが処理するドキュメンテーション・コメント内の特殊なキーワードです。タグには2つのタイプがあります。1つは\fI@tag\fRタグのように表記されるブロック・タグ(スタンドアロン・タグとも呼ばれる)、もう1つは\fI{@tag}\fRタグのように中カッコで囲んで表記されるインライン・タグです。ブロック・タグが解釈されるには、行頭のアスタリスク、空白文字、区切り文字(\fI/**\fR)を除いて、行の先頭に置く必要があります。これは、\fI@\fR文字をテキスト内の別の場所で使用しても、タグの開始として解釈されないことを意味しています。\fI@\fR文字を使用して行を開始しても、それが解釈されないようにするには、HTMLエンティティ\fI@\fRを使用します。それぞれのブロック・タグには、関連付けられたテキストがあります。このテキストは、タグの後から、次のタグの前、またはドキュメンテーション・コメントの最後までの間に記述されたテキストです(タグまたはコメント区切り文字を除く)。この関連テキストは、複数行にわたって記述できます。インライン・タグは、テキストを記述できる場所であればどこにでも置くことができ、解釈されます。次の例にはブロック・タグ\fI@deprecated\fRとインライン・タグ\fI{@link}\fRが含まれています。javadocタグを参照してください。 1144 .sp 1145 .if n \{\ 1146 .RS 4 1147 .\} 1148 .nf 1149 /** 1150 * @deprecated As of JDK 1\&.1, replaced by {@link #setBounds(int,int,int,int)} 1151 */ 1152 .fi 1153 .if n \{\ 1154 .RE 1155 .\} 1156 HTMLでのコメントの記述.PP 1157 テキストはHTMLエンティティとHTMLタグを使用してHTMLで記述される必要があります。使用するブラウザがサポートする任意のHTMLのバージョンを使用できます。標準ドックレットは、カスケーディング・スタイル・シートおよびフレームを含め、ドキュメンテーション・コメント以外の部分でHTML 3\&.2に準拠したコードを生成します。フレーム・セットのため、生成されたファイルにはHTML 4\&.0が推奨されます。 1158 .PP 1159 たとえば、より小さい記号(<)およびより大きい記号(>)のエンティティは、\fI<\fRおよび\fI>\fRと記述する必要があります。同様に、アンパサンド(&)は\fI&\fRと記述する必要があります。次の例では、太字のHTMLタグ\fI<b>\fRを使用しています。 1160 .sp 1161 .if n \{\ 1162 .RS 4 1163 .\} 1164 .nf 1165 /** 1166 * This is a <b>doc</b> comment\&. 1167 * @see java\&.lang\&.Object 1168 */ 1169 .fi 1170 .if n \{\ 1171 .RE 1172 .\} 1173 先頭のアスタリスク.PP 1174 \fIjavadoc\fRコマンドによるドキュメンテーション・コメントの解析時に、各行の先頭にあるアスタリスク(*)文字は破棄されます。最初のアスタリスク(*)文字より前にある空白やタブも破棄されます。行頭のアスタリスクを省略した場合、インデントを保持したままでサンプル・コードを\fI<PRE>\fRタグ内のドキュメンテーション・コメントに直接貼り付けられるように、先頭の空白文字は削除されなくなります。ブラウザは、空白文字をタブよりも一律に解釈します。インデントの起点は(区切り文字\fI/**\fRまたは\fI<PRE>\fRタグではなく)左マージンになります。 1175 最初の文.PP 1176 各ドキュメンテーション・コメントの最初の文は、宣言されているエンティティに関する簡潔かつ完全なサマリー文である必要があります。この文は、空白、タブ、または行終了文字が続く最初のピリオド、または最初のブロック・タグがある位置で終わります。最初の文は、\fIjavadoc\fRコマンドによってHTMLページの先頭にあるメンバーのサマリーの部分にコピーされます。 1177 複数フィールドの宣言.PP 1178 Javaプラットフォームでは、1つの文で複数のフィールドを宣言できます。ただし、この文には、1つのドキュメンテーション・コメントしか記述できません。そのコメントが、すべてのフィールドに対してコピーされます。フィールドごとにドキュメンテーション・コメントを記述する必要がある場合は、各フィールドを別々の文で宣言する必要があります。たとえば、次のドキュメンテーション・コメントは、1つの宣言として記述すると不適切です。この場合は、宣言を2つに分けることをお薦めします。 1179 .sp 1180 .if n \{\ 1181 .RS 4 1182 .\} 1183 .nf 1184 /** 1185 * The horizontal and vertical distances of point (x,y) 1186 */ 1187 public int x, y; // Avoid this 1188 1189 .fi 1190 .if n \{\ 1191 .RE 1192 .\} 1193 .PP 1194 \fIjavadoc\fRコマンドは、上のコードから次のようなドキュメントを生成します。 1195 .sp 1196 .if n \{\ 1197 .RS 4 1198 .\} 1199 .nf 1200 public int x 1201 .fi 1202 .if n \{\ 1203 .RE 1204 .\} 1205 .PP 1206 The horizontal and vertical distances of point (x, y)\&. 1207 .sp 1208 .if n \{\ 1209 .RS 4 1210 .\} 1211 .nf 1212 public int y 1213 .fi 1214 .if n \{\ 1215 .RE 1216 .\} 1217 .PP 1218 The horizontal and vertical distances of point (x, y)\&. 1219 ヘッダー・タグの使用.PP 1220 メンバーに対してドキュメンテーション・コメントを記述するときには、\fI<H1>\fRや\fI<H2>\fRなどのHTML見出しタグを使用しないことをお薦めします。\fIjavadoc\fRコマンドは、完全な構造化ドキュメントを作成するので、このような構造化タグが使用されていると、生成ドキュメントの形式が悪影響を受けることがあります。ただし、クラスやパッケージのコメントでは、これらの見出しを使用して独自の構造を指定してかまいません。 1221 .SS "メソッド・コメントの継承" 1222 .PP 1223 \fIjavadoc\fRコマンドでは、クラスおよびインタフェースでメソッド・コメントを継承して、欠落したテキストを入力したり、明示的にメソッド・コメントを継承することができます。コンストラクタ、フィールド、およびネストされたクラスは、ドキュメンテーション・コメントを継承しません。 1224 .PP 1225 \fB注意:\fR 1226 ドキュメンテーション・コメントをコピーに利用するには、継承したメソッドのソース・ファイルが\fI\-sourcepath\fRオプションで指定したパスのみに置かれている必要があります。コマンドラインで、クラスもパッケージも渡す必要はありません。この点はリリース1\&.3\&.\fIn\fR以前とは対照的です。これまでは、クラスがドキュメント化されるクラスであることが必要でした。 1227 欠落テキストの入力.PP 1228 主説明、または\fI@return\fR、\fI@param\fR、\fI@throws\fRタグがメソッド・コメントから欠落している場合、\fIjavadoc\fRコマンドは、対応する主説明またはタグ・コメントを、それがオーバーライドまたは実装しているメソッド(ある場合)からコピーします。メソッド・コメントの継承を参照してください。 1229 .PP 1230 特定のパラメータの\fI@param\fRタグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の\fI@throws\fRタグが見つからない場合、その例外が宣言されている場合にかぎり、\fI@throws\fRタグがコピーされます。 1231 .PP 1232 この動作はリリース1\&.3以前の動作とは対照的です。これまでのバージョンでは、主説明またはタグが存在すれば、コメントは一切継承されませんでした。 1233 .PP 1234 javadocタグおよびオプションを参照してください。 1235 明示的な継承.PP 1236 \fI{@inheritDoc}\fRインライン・タグをメソッドの主説明または\fI@return\fR、\fI@param\fR、\fI@throws\fRタグ・コメントに挿入します。対応する継承された主説明またはタグ・コメントは、その場所にコピーされます。 1237 .SS "クラスおよびインタフェースの継承" 1238 .PP 1239 コメントの継承は、クラスおよびインタフェースからの継承の、考えられるすべての場合に発生します。 1240 .sp 1241 .RS 4 1242 .ie n \{\ 1243 \h'-04'\(bu\h'+03'\c 1244 .\} 1245 .el \{\ 1246 .sp -1 1247 .IP \(bu 2.3 1248 .\} 1249 クラスのメソッドがスーパークラスのメソッドをオーバーライドしている場合 1250 .RE 1251 .sp 1252 .RS 4 1253 .ie n \{\ 1254 \h'-04'\(bu\h'+03'\c 1255 .\} 1256 .el \{\ 1257 .sp -1 1258 .IP \(bu 2.3 1259 .\} 1260 インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている場合 1261 .RE 1262 .sp 1263 .RS 4 1264 .ie n \{\ 1265 \h'-04'\(bu\h'+03'\c 1266 .\} 1267 .el \{\ 1268 .sp -1 1269 .IP \(bu 2.3 1270 .\} 1271 クラスのメソッドがインタフェースのメソッドを実装している場合 1272 .RE 1273 .PP 1274 最初の2つのケースでは、\fIjavadoc\fRコマンドは、オーバーライドしているメソッドのドキュメント内に\fI「オーバーライド」\fRという小見出しを生成します。コメントが継承されているかどうかにかかわらず、オーバーライドされているメソッドへのリンクが含まれます。 1275 .PP 1276 3つ目のケース(特定のクラスのメソッドがインタフェースのメソッドを実装している場合)では、\fIjavadoc\fRコマンドは、オーバーライドしているメソッドのドキュメント内に\fI「定義」\fRという小見出しを生成します。コメントが継承されているかどうかにかかわらず、実装されているメソッドへのリンクが含まれます。 1277 .SS "メソッド・コメントのアルゴリズム" 1278 .PP 1279 メソッドにドキュメンテーション・コメントがない、または\fI{@inheritDoc}\fRタグがある場合、\fIjavadoc\fRコマンドは次のアルゴリズムを使用して適用できるコメントを検索します。アルゴリズムは、最も特定される適用可能なドキュメンテーション・コメントを探し、スーパークラスよりもインタフェースを優先するように設計されています。 1280 .sp 1281 .RS 4 1282 .ie n \{\ 1283 \h'-04' 1.\h'+01'\c 1284 .\} 1285 .el \{\ 1286 .sp -1 1287 .IP " 1." 4.2 1288 .\} 1289 直接に実装されている(または、拡張されている)インタフェースを、メソッドの宣言で\fIimplements\fR(または\fIextends\fR)という語の後に出現する順序で、1つずつ調べます。このメソッドについて最初に見つかったドキュメンテーション・コメントを採用します。 1290 .RE 1291 .sp 1292 .RS 4 1293 .ie n \{\ 1294 \h'-04' 2.\h'+01'\c 1295 .\} 1296 .el \{\ 1297 .sp -1 1298 .IP " 2." 4.2 1299 .\} 1300 手順1でドキュメンテーション・コメントが見つからなかった場合は、直接実装されている(または、拡張されている)インタフェースのそれぞれに対して、このアルゴリズム全体を再帰的に適用します(その際の順序は、手順1でインタフェースを調べたときの順序と同じ)。 1301 .RE 1302 .sp 1303 .RS 4 1304 .ie n \{\ 1305 \h'-04' 3.\h'+01'\c 1306 .\} 1307 .el \{\ 1308 .sp -1 1309 .IP " 3." 4.2 1310 .\} 1311 手順2でドキュメンテーション・コメントが見つからなかった場合で、このクラスが\fIObject\fR以外のクラスであるが、インタフェースではない場合は、次のように処理します。 1312 .sp 1313 .RS 4 1314 .ie n \{\ 1315 \h'-04' 1.\h'+01'\c 1316 .\} 1317 .el \{\ 1318 .sp -1 1319 .IP " 1." 4.2 1320 .\} 1321 スーパークラスにこのメソッドについてのドキュメンテーション・コメントが記述されている場合は、そのコメントを採用します。 1322 .RE 1323 .sp 1324 .RS 4 1325 .ie n \{\ 1326 \h'-04' 2.\h'+01'\c 1327 .\} 1328 .el \{\ 1329 .sp -1 1330 .IP " 2." 4.2 1331 .\} 1332 手順3aでドキュメンテーション・コメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を再帰的に適用します。 1333 .RE 1334 .RE 1335 .SH "JAVADOCタグ" 1336 .PP 1337 \fIjavadoc\fRコマンドは、Javaのドキュメンテーション・コメント内に埋め込まれた特別なタグを解析します。\fIjavadoc\fRタグを使用すると、完全な整形式のAPIをソース・コードから自動的に生成できます。タグはアットマーク記号(\fI@\fR)で始まり、大文字と小文字が区別されます。これらのタグは、表示されているとおりに大文字と小文字を使用して入力する必要があります。タグは、行の先頭(先頭の空白文字と省略可能なアスタリスクの後)に置く必要があります。そうしないと、テキストとして扱われます。慣例として、同じ名前のタグは1箇所にまとめます。たとえば、\fI@see\fRタグが複数ある場合は、すべて同じ場所にまとめて配置します。詳細は、タグを使用できる場所を参照してください。 1338 .PP 1339 タグには、次のタイプがあります。 1340 .sp 1341 .RS 4 1342 .ie n \{\ 1343 \h'-04'\(bu\h'+03'\c 1344 .\} 1345 .el \{\ 1346 .sp -1 1347 .IP \(bu 2.3 1348 .\} 1349 ブロック・タグ: ブロック・タグは主説明に続くタグ・セクション内にのみ配置します。ブロック・タグは、\fI@tag\fRの形式をとります。 1350 .RE 1351 .sp 1352 .RS 4 1353 .ie n \{\ 1354 \h'-04'\(bu\h'+03'\c 1355 .\} 1356 .el \{\ 1357 .sp -1 1358 .IP \(bu 2.3 1359 .\} 1360 インライン・タグ: インライン・タグは主説明内またはブロック・タグのコメント内の任意の場所に配置します。インライン・タグは\fI{@tag}\fRのように中カッコで囲みます。 1361 .RE 1362 .PP 1363 カスタム・タグについては、\-tag tagname:Xaoptcmf:"taghead"を参照してください。タグを使用できる場所も参照してください。 1364 .SS "タグの説明" 1365 .PP 1366 @author \fIname\-text\fR 1367 .RS 4 1368 JDK 1\&.0で導入 1369 .sp 1370 \fI\-author\fRオプションが使用されている場合、指定した名前のテキストの作成者エントリを生成されるドキュメントに追加します。1つのドキュメンテーション・コメントに複数の\fI@author\fRタグを含めることができます。1つの\fI@author\fRタグに1つの名前を指定することも、複数の名前を指定することもできます。前者の場合は、\fIjavadoc\fRコマンドによって名前と名前の間にカンマ(,)と空白文字が挿入されます。後者の場合は、テキスト全体が解析されることなく、生成ドキュメントにコピーされます。したがって、カンマではなく、各言語に対応した名前区切り文字を使用する必要があるときに、1行に複数の名前を指定できます。JavadocツールでのDocコメントの記述方法の@authorに関する項 1371 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@author)を参照してください。 1372 .RE 1373 .PP 1374 {@code \fItext\fR} 1375 .RS 4 1376 JDK 1\&.5で導入 1377 .sp 1378 \fI<code>{@literal}</code>\fRと同等です。 1379 .sp 1380 テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textをコード・フォントで表示します。これにより、ドキュメンテーション・コメントでは、パラメータの型(\fI<Object>\fR)、不等号(\fI3 < 4\fR)、矢印(\fI<\-\fR)などで、通常の山カッコ(<および>)をHTMLエンティティ(\fI<\fRおよび\fI>\fR)のかわりに使用できます。たとえば、ドキュメンテーション・コメント\fI{@code A<B>C}\fRは\fIA<B>C\fRとして変更されずに生成されたHTMLページに表示されます。つまり、\fI<B>\fRが太字として解釈されず、そのフォントはコード・フォントになります。コード・フォントなしで同じ機能を実現するには、\fI{@literal}\fRタグを使用します。 1381 .RE 1382 .PP 1383 @deprecated \fIdeprecated\-text\fR 1384 .RS 4 1385 JDK 1\&.0で導入 1386 .sp 1387 このAPIは動作し続けますが、このAPIを使用しないことを薦めるコメントを追加します。\fIjavadoc\fRコマンドは、\fIdeprecated\-text\fRを主説明の前に移動してイタリックにし、その前に太字の警告「推奨されていません。」を追加します。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 1388 .sp 1389 非推奨テキストの最初の文では、そのAPIが推奨されなくなった時期と、代替として使用するAPIをユーザーに提示する必要があります。\fIjavadoc\fRコマンドは、この最初の文を、サマリー・セクションと索引にコピーします。その後の文で非推奨になった理由を説明することもできます。代替APIを指し示す\fI{@link}\fRタグ(Javadoc 1\&.2以降の場合)を含める必要があります。 1390 .sp 1391 \fI@deprecated annotation\fRタグを使用してプログラム要素を非推奨にします。APIを非推奨にする方法と時期 1392 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation\&.html)を参照してください。 1393 .sp 1394 JavadocツールでのDocコメントの記述方法の@deprecatedに関する項 1395 1396 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@deprecated)も参照してください。 1397 .RE 1398 .PP 1399 {@docRoot} 1400 .RS 4 1401 JDK 1\&.3で導入 1402 .sp 1403 生成されるページからの、生成ドキュメントの(生成先)ルート・ディレクトリへの相対パスを表します。このタグは、著作権のページや会社のロゴなど、生成されるすべてのページから参照するファイルを組み込むときに便利です。通常は、各ページの最下部から著作権のページにリンクします。 1404 .sp 1405 この\fI{@docRoot}\fRタグは、コマンドラインでもドキュメンテーション・コメント内でも使用できます。このタグは、任意のタグ(\fI@return\fR、\fI@param\fRおよび\fI@deprecated\fRタグなど)のテキスト部分を含む、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 1406 .sp 1407 .RS 4 1408 .ie n \{\ 1409 \h'-04'\(bu\h'+03'\c 1410 .\} 1411 .el \{\ 1412 .sp -1 1413 .IP \(bu 2.3 1414 .\} 1415 コマンドラインで、ヘッダー、フッターまたは最下部が次のように定義されます。\fIjavadoc \-bottom \*(Aq<a href="{@docRoot}/copyright\&.html">Copyright</a>\*(Aq\fR 1416 .sp 1417 \fI{@docRoot}\fRタグをmakefile内でこのように利用する場合、一部の\fImakefile\fRプログラムでは、中カッコ\fI{}\fR文字を特別にエスケープする必要があります。たとえば、Inprise MAKEバージョン5\&.2をWindows上で実行する場合は、\fI{{@docRoot}}\fRのように、中カッコを二重にする必要があります。\fI\-bottom\fRオプションなどのオプションへの引数を囲むのに、二重(一重ではなく)引用符も必要です(\fIhref\fR引数を囲む引用符は省略)。 1418 .RE 1419 .sp 1420 .RS 4 1421 .ie n \{\ 1422 \h'-04'\(bu\h'+03'\c 1423 .\} 1424 .el \{\ 1425 .sp -1 1426 .IP \(bu 2.3 1427 .\} 1428 ドキュメンテーション・コメントでは 1429 .sp 1430 .if n \{\ 1431 .RS 4 1432 .\} 1433 .nf 1434 /** 1435 * See the <a href="{@docRoot}/copyright\&.html">Copyright</a>\&. 1436 */ 1437 .fi 1438 .if n \{\ 1439 .RE 1440 .\} 1441 このタグが必要な理由は、生成ドキュメントが、サブパッケージと同じ深さを持つ階層構造のディレクトリに格納されるからです。式\fI<a href="{@docRoot}/copyright\&.html">\fRは、\fIjava/lang/Object\&.java\fRに対しては\fI<a href="\&.\&./\&.\&./copyright\&.html">\fRに解決され、\fIjava/lang/ref/Reference\&.java\fRに対しては\fI<a href="\&.\&./\&.\&./\&.\&./copyright\&.html">\fRに解決されます。 1442 .RE 1443 .RE 1444 .PP 1445 @exception \fIclass\-name description\fR 1446 .RS 4 1447 JDK 1\&.0で導入 1448 .sp 1449 \fI@throws\fRタグと同じです。@throws class\-name descriptionを参照してください。 1450 .RE 1451 .PP 1452 {@inheritDoc} 1453 .RS 4 1454 JDK 1\&.4で導入 1455 .sp 1456 最も近い継承可能なクラスまたは実装可能なインタフェースから、このタグの位置にある現在のドキュメンテーション・コメントに、ドキュメントを継承(コピー)します。これにより、より汎用的なコメントを継承ツリーの上位に記述し、コピーしたテキストを使用して記述することができます。 1457 .sp 1458 このタグは、ドキュメンテーション・コメントの次の位置でのみ有効です。 1459 .sp 1460 .RS 4 1461 .ie n \{\ 1462 \h'-04'\(bu\h'+03'\c 1463 .\} 1464 .el \{\ 1465 .sp -1 1466 .IP \(bu 2.3 1467 .\} 1468 メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされます。 1469 .RE 1470 .sp 1471 .RS 4 1472 .ie n \{\ 1473 \h'-04'\(bu\h'+03'\c 1474 .\} 1475 .el \{\ 1476 .sp -1 1477 .IP \(bu 2.3 1478 .\} 1479 メソッドの\fI@return\fR、\fI@param\fR、\fI@throws\fRタグのテキスト引数内。この場合、タグ・テキストは、上位階層の対応するタグからコピーされます。 1480 .RE 1481 .sp 1482 継承階層でコメントを見つける方法に関する説明は、メソッド・コメントの継承を参照してください。このタグが見つからない場合、コメントは、この項で説明するルールに応じて、自動的に継承されるかどうかが決まります。 1483 .RE 1484 .PP 1485 {@link \fIpackage\&.class#member label\fR} 1486 .RS 4 1487 JDK 1\&.2で導入 1488 .sp 1489 表示テキストlabelとともにインライン・リンクを挿入します。labelは、参照クラスの指定されたパッケージ、クラス、またはメンバーの名前のドキュメントを指し示します。このタグは、\fI@return\fR、\fI@param\fRおよび\fI@deprecated\fRタグなどの任意のタグのテキスト部分を含む、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。JavadocツールでのDocコメントの記述方法の@linkに関する項 1490 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#{@link)を参照してください。 1491 .sp 1492 このタグは\fI@see\fRタグに似ています。どちらのタグも、\fIpackage\&.class#member\fRと\fIlabel\fRの参照方法と、有効な構文が同じです。主な違いは、\fI{@link}\fRタグでは、「関連項目」セクションにリンクが配置されるかわりに、インライン・リンクが生成されるという点です。インライン・テキストの他の部分と区別するために、\fI{@link}\fRタグの最初と最後に中カッコを記述します。ラベル内で右中カッコ(\fI}\fR)を使用する必要がある場合、HTMLエンティティ記法\fI}\fRを使用します。 1493 .sp 1494 1つ文の中で使用できる\fI{@link}\fRタグの数に制限はありません。このタグは、ドキュメンテーション・コメントの主説明部分、または\fI@deprecated\fR、\fI@return\fR、\fI@param\fRタグなどの任意のタグのテキスト部分で使用できます。 1495 .sp 1496 たとえば、次のコメントでは\fIgetComponentAt(int,int)\fRメソッドを参照しています。 1497 .sp 1498 .if n \{\ 1499 .RS 4 1500 .\} 1501 .nf 1502 Use the {@link #getComponentAt(int, int) getComponentAt} method\&. 1503 .fi 1504 .if n \{\ 1505 .RE 1506 .\} 1507 標準ドックレットでは、このコードから次のHTMLが生成されます(このコメントが同じパッケージの別のクラスを参照している場合)。 1508 .sp 1509 .if n \{\ 1510 .RS 4 1511 .\} 1512 .nf 1513 Use the <a href="Component\&.html#getComponentAt(int, int)">getComponentAt</a> method\&. 1514 .fi 1515 .if n \{\ 1516 .RE 1517 .\} 1518 前の行は、次のようにWebページに表示されます。 1519 .sp 1520 .if n \{\ 1521 .RS 4 1522 .\} 1523 .nf 1524 Use the getComponentAt method\&. 1525 .fi 1526 .if n \{\ 1527 .RE 1528 .\} 1529 .RE 1530 .PP 1531 {@linkplain \fIpackage\&.class#member label\fR} 1532 .RS 4 1533 JDK 1\&.4で導入 1534 .sp 1535 \fI{@link}\fRタグと同じ動作をしますが、リンク・ラベルがコード・フォントではなくプレーン・テキストで表示される点が異なります。ラベルがプレーン・テキストで記述されていると便利です。たとえば、「\fIRefer to {@linkplain add() the overridden method}\fR\&.」は「Refer to the overridden method」と表示されます。 1536 .RE 1537 .PP 1538 {@literal \fItext\fR} 1539 .RS 4 1540 JDK 1\&.5で導入 1541 .sp 1542 テキストをHTMLマークアップまたはネストされたJavadocタグとして解釈せずに、textを表示します。これにより、ドキュメンテーション・コメントでは、パラメータの型(\fI<Object>\fR)、不等号(\fI3 < 4\fR)、矢印(<\-)などで、山カッコ(\fI<および>\fR)をHTMLエンティティ(\fI<\fRおよび\fI>\fR)のかわりに使用できます。たとえば、ドキュメンテーション・コメントのテキスト\fI{@literal A<B>C}\fRは\fIA<B>C\fRとして、ブラウザの生成されたHTMLページに変更されずに表示されます。\fI<B>\fRは太字として解釈されません(コード・フォントになりません)。コード・フォントで同じ機能を実現するには、\fI{@code}\fRタグを使用します。 1543 .RE 1544 .PP 1545 @param \fIparameter\-name description\fR 1546 .RS 4 1547 JDK 1\&.0で導入 1548 .sp 1549 「パラメータ」セクションに、指定された\fIparameter\-name\fRの後に指定されたdescriptionを続けてパラメータを追加します。ドキュメンテーション・コメントを記述するときには、descriptionを複数行にわたって記述することもできます。このタグは、メソッド、コンストラクタ、またはクラスのドキュメンテーション・コメント内でのみ有効です。JavadocツールでのDocコメントの記述方法の@paramに関する項 1550 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@param)を参照してください。 1551 .sp 1552 \fIparameter\-name\fRは、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタの型パラメータの名前になります。山カッコでこのパラメータ名を囲み、型パラメータを使用することを指定します。 1553 .sp 1554 クラスの型パラメータの例: 1555 .sp 1556 .if n \{\ 1557 .RS 4 1558 .\} 1559 .nf 1560 /** 1561 * @param <E> Type of element stored in a list 1562 */ 1563 public interface List<E> extends Collection<E> { 1564 } 1565 .fi 1566 .if n \{\ 1567 .RE 1568 .\} 1569 メソッドの型パラメータの例: 1570 .sp 1571 .if n \{\ 1572 .RS 4 1573 .\} 1574 .nf 1575 /** 1576 * @param string the string to be converted 1577 * @param type the type to convert the string to 1578 * @param <T> the type of the element 1579 * @param <V> the value of the element 1580 */ 1581 <T, V extends T> V convert(String string, Class<T> type) { 1582 } 1583 .fi 1584 .if n \{\ 1585 .RE 1586 .\} 1587 .RE 1588 .PP 1589 @return \fIdescription\fR 1590 .RS 4 1591 JDK 1\&.0で導入 1592 .sp 1593 「戻り値」セクションを追加して、descriptionのテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーション・コメントでのみ有効です。JavadocツールでのDocコメントの記述方法の@returnに関する項 1594 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@return)を参照してください。 1595 .RE 1596 .PP 1597 @see \fIreference\fR 1598 .RS 4 1599 JDK 1\&.0で導入 1600 .sp 1601 \fI「関連項目」\fR見出しを追加して、referenceを指すリンク、またはテキスト・エントリを書き込みます。1つのドキュメンテーション・コメントには任意の数の\fI@see\fRタグを含めることができますが、それらはすべて同じ見出しの下にグループ化されます。\fI@see\fRタグには、3つのタイプの形式があります。この形式が最も一般的です。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドで有効です。パッケージ、クラス、またはメンバーに対するインライン・リンクを文中に挿入する方法は、\fI{@link}\fRを参照してください。 1602 .sp 1603 \fB形式1\fR。@see 1604 \fIstring\fRタグ形式は、\fIstring\fRのテキスト・エントリを追加します。リンクは生成されません。stringは、書籍またはURLではアクセスできない情報の参照先です。\fIjavadoc\fRコマンドは、最初の文字として二重引用符(")を検索して、この形式を前述の形式と区別します。たとえば、\fI@see "The Java Programming Language"\fRは次のテキストを生成します。 1605 .sp 1606 \fB関連項目\fR: 1607 .sp 1608 "The Java Programming Language" 1609 .sp 1610 \fB形式2\fR。\fI@see <a href="URL#value">label</a>\fR形式は、\fIURL#value\fRにより定義されたリンクを追加します。\fIURL#value\fRパラメータは、相対URLまたは絶対URLです。\fIjavadoc\fRコマンドは、最初の文字として「より小さい」記号(\fI<\fR)を検索して、この形式を他の形式と区別します。たとえば、\fI@see <a href="spec\&.html#section">Java Spec</a>\fRは次のリンクを生成します。 1611 .sp 1612 \fB関連項目\fR: 1613 .sp 1614 Java Spec 1615 .sp 1616 \fB形式3\fR。\fI@see package\&.class#member label\fR形式は、表示テキスト・ラベルとともにリンクを追加します。このラベルは参照されているJava言語の指定された名前のドキュメントを指し示します。ラベルはオプションです。ラベルを省略した場合は、表示テキストのかわりに、名前が適切に短縮されて表示されます。\fI\-noqualifier\fRオプションを使用すると、この表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストにする場合に使用します。「名前が表示される方法」を参照してください。 1617 .sp 1618 Java SE 1\&.2だけは、ラベルではなく名前が\fI<code>\fR 1619 HTMLタグ内に自動的に表示されます。Java SE 1\&.2\&.2からは、ラベルを使用するかしないかにかかわらず、\fI<code>\fRタグは常に表示テキストを囲むかたちで含まれます。 1620 .sp 1621 .RS 4 1622 .ie n \{\ 1623 \h'-04'\(bu\h'+03'\c 1624 .\} 1625 .el \{\ 1626 .sp -1 1627 .IP \(bu 2.3 1628 .\} 1629 \fIpackage\&.class#member\fRには、参照されている任意の有効なプログラム要素の名前を指定します。つまり、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドの名前です。ただし、メンバー名の前の文字は、シャープ記号(\fI#\fR)にする必要があります。classは、任意のトップレベルまたはネストされたクラスか、インタフェースを表します。memberは、任意のコンストラクタ、メソッドまたはフィールドを表します(ネストされたクラスまたはインタフェースではありません)。この名前が、ドキュメント化されるクラスに含まれている場合、\fIjavadoc\fRコマンドは、その名前へのリンクを作成します。外部参照クラスへのリンクを作成するには、\fI\-link\fRオプションを使用します。参照クラスに属していない名前のドキュメントを参照するには、他の2つの\fI@see\fRタグ形式のどちらかを使用します。「名前の指定」を参照してください。 1630 .sp 1631 \fB注意:\fR 1632 外部参照クラスは、コマンドラインで\fIjavadoc\fRコマンドに渡されないクラスです。生成ドキュメント内で外部参照クラスにリンクしている箇所は、外部参照または外部リンクと呼ばれます。たとえば、\fIjava\&.awt package\fRに対してのみ\fIjavadoc\fRコマンドを実行した場合、\fIObject\fRなどの\fIjava\&.lang\fR内のすべてのクラスが外部参照クラスになります。\fI\-link\fRおよび\fI\-linkoffline\fRオプションを使用して、外部参照クラスへリンクします。外部参照クラスのソース・コメントは\fIjavadoc\fRコマンドの実行には使用できません。 1633 .RE 1634 .sp 1635 .RS 4 1636 .ie n \{\ 1637 \h'-04'\(bu\h'+03'\c 1638 .\} 1639 .el \{\ 1640 .sp -1 1641 .IP \(bu 2.3 1642 .\} 1643 \fIlabel\fRは、省略可能なテキストで、リンクのラベルとして表示されます。ラベルには空白を含めることができます。\fIlabel\fRを省略すると、\fIpackage\&.class\&.member\fRが、現在のクラスおよびパッケージに応じて適切に短縮されて表示されます。「名前が表示される方法」を参照してください。 1644 .RE 1645 .sp 1646 .RS 4 1647 .ie n \{\ 1648 \h'-04'\(bu\h'+03'\c 1649 .\} 1650 .el \{\ 1651 .sp -1 1652 .IP \(bu 2.3 1653 .\} 1654 空白文字が、\fIpackage\&.class#member\fRと\fIlabel\fRの間の区切り文字になります。カッコの内側の空白文字はラベルの先頭とは解釈されないため、メソッドのパラメータ間に空白文字を入れてもかまいません。 1655 .RE 1656 .sp 1657 この例では、\fI@see\fRタグ(\fICharacter\fRクラス内)が、\fIString\fRクラスのequalsメソッドを参照しています。タグには、名前\fIString#equals(Object)\fRとラベル\fIequals\fRの両方の引数が含まれています。 1658 .sp 1659 .if n \{\ 1660 .RS 4 1661 .\} 1662 .nf 1663 /** 1664 * @see String#equals(Object) equals 1665 */ 1666 .fi 1667 .if n \{\ 1668 .RE 1669 .\} 1670 標準ドックレットは、次のようなHTMLを生成します。 1671 .sp 1672 .if n \{\ 1673 .RS 4 1674 .\} 1675 .nf 1676 <dl> 1677 <dt><b>See Also:</b> 1678 <dd><a href="\&.\&./\&.\&./java/lang/String#equals(java\&.lang\&.Object)"><code>equals<code></a> 1679 </dl> 1680 .fi 1681 .if n \{\ 1682 .RE 1683 .\} 1684 前述のコードは、ブラウザに次のように表示され、ラベルは表示リンク・テキストになっています。 1685 .sp 1686 \fB関連項目\fR: 1687 .sp 1688 equals 1689 .RE 1690 名前の指定.PP 1691 この\fIpackage\&.class#member\fRという名前は、\fIjava\&.lang\&.String#toUpperCase()\fRのような完全修飾名にすることも、\fIString#toUpperCase()\fRや\fI#toUpperCase()\fRのような非完全修飾名にすることもできます。名前が完全修飾より短い場合は、\fIjavadoc\fRコマンドは、標準のJavaコンパイラの検索順序を使用して探します。「@seeタグの検索順序」を参照してください。名前は、メソッド引数の間など、カッコ内のスペースを含めることができます。部分的に修飾した短い名前を指定することの利点は、入力する文字数が減ることや、ソース・コードが読みやすくなることです。次のリストに様々な形式の名前を示します。ここで、\fIClass\fRにはクラスまたはインタフェースを、Typeにはクラス、インタフェース、配列、またはプリミティブを、methodにはメソッドまたはコンストラクタを、それぞれ指定できます。 1692 .sp 1693 .if n \{\ 1694 .RS 4 1695 .\} 1696 .nf 1697 \fBTypical forms for\fR\fB @see package\&.class#member\fR 1698 \fBReferencing a member of the current class\fR 1699 @see #field 1700 @see #method(Type, Type,\&.\&.\&.) 1701 @see #method(Type argname, Type argname,\&.\&.\&.) 1702 @see #constructor(Type, Type,\&.\&.\&.) 1703 @see #constructor(Type argname, Type argname,\&.\&.\&.) 1704 1705 \fBReferencing another class in the current or imported packages\fR 1706 @see Class#field 1707 @see Class#method(Type, Type,\&.\&.\&.) 1708 @see Class#method(Type argname, Type argname,\&.\&.\&.) 1709 @see Class#constructor(Type, Type,\&.\&.\&.) 1710 @see Class#constructor(Type argname, Type argname,\&.\&.\&.) 1711 @see Class\&.NestedClass 1712 @see Class 1713 1714 \fBReferencing an element in another package (fully qualified)\fR 1715 @see package\&.Class#field 1716 @see package\&.Class#method(Type, Type,\&.\&.\&.) 1717 @see package\&.Class#method(Type argname, Type argname,\&.\&.\&.) 1718 @see package\&.Class#constructor(Type, Type,\&.\&.\&.) 1719 @see package\&.Class#constructor(Type argname, Type argname,\&.\&.\&.) 1720 @see package\&.Class\&.NestedClass 1721 @see package\&.Class 1722 @see package 1723 .fi 1724 .if n \{\ 1725 .RE 1726 .\} 1727 .PP 1728 前のリストに関するメモ: 1729 .sp 1730 .RS 4 1731 .ie n \{\ 1732 \h'-04'\(bu\h'+03'\c 1733 .\} 1734 .el \{\ 1735 .sp -1 1736 .IP \(bu 2.3 1737 .\} 1738 最初のタイプの形式(パッケージとクラスを省略)の場合、\fIjavadoc\fRコマンドは、現在のクラスの階層のみを検索します。つまり、現在のクラスかインタフェース、そのスーパークラスかスーパーインタフェース、またはその外側を囲んでいるクラスかインタフェースからメンバーを検索します(検索項目1\(en3)。現在のパッケージの他の部分や、他のパッケージは検索しません(検索項目4\(en5)。「@seeタグの検索順序」を参照してください。 1739 .RE 1740 .sp 1741 .RS 4 1742 .ie n \{\ 1743 \h'-04'\(bu\h'+03'\c 1744 .\} 1745 .el \{\ 1746 .sp -1 1747 .IP \(bu 2.3 1748 .\} 1749 メソッドまたはコンストラクタの入力時に、\fIgetValue\fRのようにカッコなしの名前を使用した場合、同じ名前のフィールドが存在していなければ、\fIjavadoc\fRコマンドはそのメソッドへのリンクを作成します。このメソッドがオーバーロードされている場合、\fIjavadoc\fRコマンドは、検索で最初に見つかったメソッドにリンクします。結果は前もって特定できません。 1750 .RE 1751 .sp 1752 .RS 4 1753 .ie n \{\ 1754 \h'-04'\(bu\h'+03'\c 1755 .\} 1756 .el \{\ 1757 .sp -1 1758 .IP \(bu 2.3 1759 .\} 1760 ネストされたクラスは、すべての形式について、\fIouter\&.inner\fRとして指定する必要があります。単純に\fIinner\fRとはしないでください。 1761 .RE 1762 .sp 1763 .RS 4 1764 .ie n \{\ 1765 \h'-04'\(bu\h'+03'\c 1766 .\} 1767 .el \{\ 1768 .sp -1 1769 .IP \(bu 2.3 1770 .\} 1771 すでに述べたように、クラスとメンバーとの間の区切り文字としては、ドット(\fI\&.\fR)ではなくシャープ記号(\fI#\fR)を使用します。このように指定すると、\fIjavadoc\fRコマンドは、あいまいさを解決できます。ドットは、クラス、ネストされたクラス、パッケージ、およびサブパッケージを区切るためにも使用されるからです。ただし、\fIjavadoc\fRコマンドでは、あいまいさがなければドットは正しく解析されますが、警告は表示されます。 1772 .RE 1773 @seeタグの検索順序.PP 1774 \fIjavadoc\fRコマンドは、ソース・ファイル、パッケージ・ファイル、概要ファイルに表示される\fI@see\fRタグを処理します。後者の2つのファイルでは、完全修飾の名前を\fI@see\fRタグに指定する必要があります。ソース・ファイルでは、完全修飾の名前、または部分修飾の名前を指定できます。 1775 .PP 1776 次に、\fI@see\fRタグの検索順序を示します。 1777 .sp 1778 .RS 4 1779 .ie n \{\ 1780 \h'-04' 1.\h'+01'\c 1781 .\} 1782 .el \{\ 1783 .sp -1 1784 .IP " 1." 4.2 1785 .\} 1786 現在のクラスまたはインタフェース。 1787 .RE 1788 .sp 1789 .RS 4 1790 .ie n \{\ 1791 \h'-04' 2.\h'+01'\c 1792 .\} 1793 .el \{\ 1794 .sp -1 1795 .IP " 2." 4.2 1796 .\} 1797 外側を囲んでいるクラスとインタフェース(最も近いものから検索)。 1798 .RE 1799 .sp 1800 .RS 4 1801 .ie n \{\ 1802 \h'-04' 3.\h'+01'\c 1803 .\} 1804 .el \{\ 1805 .sp -1 1806 .IP " 3." 4.2 1807 .\} 1808 スーパークラスとスーパーインタフェース(最も近いものから検索)。 1809 .RE 1810 .sp 1811 .RS 4 1812 .ie n \{\ 1813 \h'-04' 4.\h'+01'\c 1814 .\} 1815 .el \{\ 1816 .sp -1 1817 .IP " 4." 4.2 1818 .\} 1819 現在のパッケージ。 1820 .RE 1821 .sp 1822 .RS 4 1823 .ie n \{\ 1824 \h'-04' 5.\h'+01'\c 1825 .\} 1826 .el \{\ 1827 .sp -1 1828 .IP " 5." 4.2 1829 .\} 1830 インポートされているパッケージ、クラス、およびインタフェース(\fIimport\fR文の順序に従って検索)。 1831 .RE 1832 .PP 1833 \fIjavadoc\fRコマンドは、各クラスについて項目1\-3を再帰的に適用しながら、一致する名前が見つかるまで検索を続けます。つまり、まず現在のクラスを検索し、次にその外側を囲んでいるクラスEを検索した後、Eのスーパークラスを検索してから、Eを囲んでいるクラスを検索します。項目4と5では、\fIjavadoc\fRコマンドが1つのパッケージ内のクラスまたはインタフェースを検索する順序は決まっていません(その順序は、個々のコンパイラによって異なります)。項目5では、\fIjavadoc\fRコマンドは、\fIjava\&.lang\fRを検索します。このパッケージは、すべてのプログラムに自動的にインポートされるからです。 1834 .PP 1835 \fIjavadoc\fRコマンドは、完全修飾でないソース・ファイルで\fI@see\fRタグを見つけると、Javaコンパイラと同じ順序で指定された名前を検索します(ただし、\fIjavadoc\fRコマンドは、特定の名前空間のあいまいさを検出しません。これは、ソース・コードにこれらのエラーが存在していないことを前提としているためです)。この検索順序は、Java言語仕様で正式に定義されています。\fIjavadoc\fRコマンドは、関連するクラスとパッケージ、およびインポートされたクラスとパッケージのすべてからその名前を検索します。具体的には、次の順序で検索します。 1836 .sp 1837 .RS 4 1838 .ie n \{\ 1839 \h'-04' 1.\h'+01'\c 1840 .\} 1841 .el \{\ 1842 .sp -1 1843 .IP " 1." 4.2 1844 .\} 1845 現在のクラスまたはインタフェース。 1846 .RE 1847 .sp 1848 .RS 4 1849 .ie n \{\ 1850 \h'-04' 2.\h'+01'\c 1851 .\} 1852 .el \{\ 1853 .sp -1 1854 .IP " 2." 4.2 1855 .\} 1856 外側を囲んでいるクラスとインタフェース(最も近いものから検索)。 1857 .RE 1858 .sp 1859 .RS 4 1860 .ie n \{\ 1861 \h'-04' 3.\h'+01'\c 1862 .\} 1863 .el \{\ 1864 .sp -1 1865 .IP " 3." 4.2 1866 .\} 1867 スーパークラスとスーパーインタフェース(最も近いものから検索)。 1868 .RE 1869 .sp 1870 .RS 4 1871 .ie n \{\ 1872 \h'-04' 4.\h'+01'\c 1873 .\} 1874 .el \{\ 1875 .sp -1 1876 .IP " 4." 4.2 1877 .\} 1878 現在のパッケージ。 1879 .RE 1880 .sp 1881 .RS 4 1882 .ie n \{\ 1883 \h'-04' 5.\h'+01'\c 1884 .\} 1885 .el \{\ 1886 .sp -1 1887 .IP " 5." 4.2 1888 .\} 1889 インポートされているパッケージ、クラス、およびインタフェース(\fIimport\fR文の順序に従って検索)。 1890 .RE 1891 .PP 1892 \fIjavadoc\fRコマンドは、必ずしもサブクラスを検索するとは限りません。また、実行中に他のパッケージのドキュメントが生成される場合でも、他のパッケージを検索しません。たとえば、\fI@see\fRタグが\fIjava\&.awt\&.event\&.KeyEvent\fRクラス内に含まれていて、\fIjava\&.awt package\fR内のある名前を参照していても、そのクラスがインポートしないかぎり\fIjavadoc\fRコマンドはそのパッケージを検索しません。 1893 名前が表示される方法.PP 1894 \fIlabel\fRを省略すると、\fIpackage\&.class\&.member\fRが表示されます。一般に、これは現在のクラスおよびパッケージに応じて適切に短縮されます。短縮されるとは、\fIjavadoc\fRコマンドにより必要最小限の名前のみが表示されるということです。たとえば、\fIString\&.toUpperCase()\fRメソッドに、同じクラスのメンバーへの参照と他のクラスのメンバーへの参照が含まれている場合、クラス名が表示されるのは後者のケースのみです(次のリストを参照)。パッケージ名を全体的に削除するには、\fI\-noqualifier\fRオプションを使用します。 1895 .RS 4 1896 \fB参照のタイプ\fR: \fI@see\fRタグは同じクラス、同じパッケージのメンバーを参照します 1897 .RE 1898 .RS 4 1899 \fB例\fR: \fI@see String#toLowerCase()\fR 1900 .RE 1901 .RS 4 1902 \fB表示\fR: \fItoLowerCase()\fR \- パッケージおよびクラス名を省略します 1903 .RE 1904 .RS 4 1905 .RE 1906 .RS 4 1907 \fB参照のタイプ\fR: \fI@see\fRタグは別のクラス、同じパッケージのメンバーを参照します 1908 .RE 1909 .RS 4 1910 \fB例\fR: \fI@see Character#toLowerCase(char)\fR 1911 .RE 1912 .RS 4 1913 \fB表示\fR: \fICharacter\&.toLowerCase(char)\fR \- パッケージ名を省略し、クラス名を含みます 1914 .RE 1915 .RS 4 1916 .RE 1917 .RS 4 1918 \fB参照のタイプ\fR: \fI@see\fRタグは異なるクラス、異なるパッケージのメンバーを参照します 1919 .RE 1920 .RS 4 1921 \fB例\fR: \fI@see java\&.io\&.File#exists()\fR 1922 .RE 1923 .RS 4 1924 \fB表示\fR: \fIjava\&.io\&.File\&.exists()\fR \- パッケージおよびクラス名を含みます 1925 .RE 1926 .RS 4 1927 .RE 1928 @seeタグの例.PP 1929 右側のコメントは、\fI@see\fRタグが\fIjava\&.applet\&.Applet\fRなどの別のパッケージのクラス内にある場合に、名前がどのように表示されるかを示しています。JavadocツールでのDocコメントの記述方法の@seeに関する項 1930 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@see)を参照してください。 1931 .sp 1932 .if n \{\ 1933 .RS 4 1934 .\} 1935 .nf 1936 See also: 1937 @see java\&.lang\&.String // String 1938 @see java\&.lang\&.String The String class // The String class 1939 @see String // String 1940 @see String#equals(Object) // String\&.equals(Object) 1941 @see String#equals // String\&.equals(java\&.lang\&.Object) 1942 @see java\&.lang\&.Object#wait(long) // java\&.lang\&.Object\&.wait(long) 1943 @see Character#MAX_RADIX // Character\&.MAX_RADIX 1944 @see <a href="spec\&.html">Java Spec</a> // Java Spec 1945 @see "The Java Programming Language" // "The Java Programming Language" 1946 .fi 1947 .if n \{\ 1948 .RE 1949 .\} 1950 .PP 1951 \fB注意:\fR 1952 \fI@se\fR\fIe\fRタグを拡張してドキュメント化されないクラスにリンクするには、\fI\-link\fRオプションを使用します。 1953 .PP 1954 @serial \fIfield\-description\fR | include | exclude 1955 .RS 4 1956 JDK 1\&.2で導入 1957 .sp 1958 デフォルトの直列化可能フィールドのドキュメンテーション・コメントで使用します。クラスの直列化可能なフィールドおよびデータの文書化 1959 (http://docs\&.oracle\&.com/javase/8/docs/platform/serialization/spec/serial\-arch\&.html#5251)を参照してください 1960 .sp 1961 Oracleの直列化された形式の仕様にクラスを含める基準 1962 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/serialized\-criteria\-137781\&.html)も参照してください 1963 .sp 1964 \fIfield\-description\fR(省略可能)では、フィールドの意味を説明し、取り得る値のリストを示す必要があります。必要な場合は、複数の行に渡って説明を記述できます。標準ドックレットは、この情報を、直列化された形式ページに追加します。相互参照ページを参照してください。 1965 .sp 1966 クラスを直列化した後に直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。 1967 .sp 1968 \fIinclude\fRおよび\fIexclude\fR引数は、直列化された形式ページにクラスまたはパッケージを含めるか除外するかを示します。次のように機能します。 1969 .sp 1970 .RS 4 1971 .ie n \{\ 1972 \h'-04'\(bu\h'+03'\c 1973 .\} 1974 .el \{\ 1975 .sp -1 1976 .IP \(bu 2.3 1977 .\} 1978 \fISerializable\fRを実装しているpublicまたはprotectedクラスは、そのクラス(またはそのクラスが属するパッケージ)が\fI@serial exclude\fRタグでマークされていないかぎり、含められます。 1979 .RE 1980 .sp 1981 .RS 4 1982 .ie n \{\ 1983 \h'-04'\(bu\h'+03'\c 1984 .\} 1985 .el \{\ 1986 .sp -1 1987 .IP \(bu 2.3 1988 .\} 1989 \fISerializable\fRを実装しているprivateまたはpackage\-privateクラスは、そのクラス(またはそのクラスが属するパッケージ)が\fI@serial include\fRタグでマークされていないかぎり、除外されます。 1990 .RE 1991 .sp 1992 たとえば、\fIjavax\&.swing\fRパッケージはpackage\&.htmlまたはpackage\-info\&.java内で\fI@serial\fR 1993 \fIexclude\fRタグでマークされています。publicクラス\fIjava\&.security\&.BasicPermission\fRは\fI@serial exclude\fRタグでマークされています。package\-privateクラス\fIjava\&.util\&.PropertyPermissionCollection\fRは\fI@serial include\fRタグでマークされています。 1994 .sp 1995 クラス・レベルの\fI@serial\fRタグはパッケージ・レベルの\fI@serial\fRタグをオーバーライドします。 1996 .RE 1997 .PP 1998 @serialData \fIdata\-description\fR 1999 .RS 4 2000 JDK 1\&.2で導入 2001 .sp 2002 データの説明値を使用して、直列化された形式でのデータの型と順序をドキュメント化します。このデータには、\fIwriteObject\fRメソッドによって書き込まれる省略可能なデータ、および\fIExternalizable\&.writeExternal\fRメソッドによって書き込まれるすべてのデータ(ベース・クラスを含む)が含まれます。 2003 .sp 2004 \fI@serialData\fRタグは、\fIwriteObject\fR、\fIreadObject\fR、\fIwriteExternal\fR、\fIreadExternal\fR、\fIwriteReplace\fRおよび\fIreadResolve\fRメソッドのドキュメンテーション・コメントで使用できます。 2005 .RE 2006 .PP 2007 @serialField \fIfield\-name\fR \fIfield\-type\fR \fIfield\-description\fR 2008 .RS 4 2009 JDK 1\&.2で導入 2010 .sp 2011 \fISerializable\fRクラスの\fIserialPersistentFields\fRメンバーの\fIObjectStreamField\fRコンポーネントをドキュメント化します。\fIObjectStreamField\fRコンポーネントごとに1つの\fI@serialField\fRタグを使用します。 2012 .RE 2013 .PP 2014 @since \fIsince\-text\fR 2015 .RS 4 2016 JDK 1\&.1で導入 2017 .sp 2018 生成ドキュメントに、指定された\fIsince\-text\fRの値の\fI「導入されたバージョン」\fR見出しを追加します。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーション・コメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、またはフィールドで有効です。このタグは、特定の変更または機能が、\fIsince\-text\fRの値によって指定されたソフトウェア・リリース以降、存在していることを意味します。たとえば、\fI@since 1\&.5\fRです。 2019 .sp 2020 Javaプラットフォームのソース・コードの場合、\fI@since\fRタグは、JavaプラットフォームAPI仕様のバージョンを示します。ソース・コードがリファレンス実装に追加された時期を示すとは限りません。複数の\fI@since\fRタグを使用でき、複数の\fI@author\fRタグのように扱われます。プログラム要素が複数のAPIで使用される場合、複数のタグを使用できます。 2021 .RE 2022 .PP 2023 @throws \fIclass\-name\fR \fIdescription\fR 2024 .RS 4 2025 JDK 1\&.2で導入 2026 .sp 2027 \fI@exception\fRタグと同じ動作をします。JavadocツールでのDocコメントの記述方法の@throwsに関する項 2028 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@exception)を参照してください 2029 .sp 2030 \fI@throws\fRタグは、生成ドキュメントに\fIThrows\fR小見出しを追加して、\fIclass\-name\fRおよび\fIdescription\fRテキストを書き込みます。\fIclass\-name\fRは、そのメソッドからスローされる可能性のある例外の名前です。このタグは、メソッド、コンストラクタのドキュメンテーション・コメント内でのみ有効です。このクラスが完全指定の名前で記述されていない場合、\fIjavadoc\fRコマンドは、検索順序に従ってクラスを探します。複数の\fI@throws\fRタグを、同じ例外または違う例外の指定したドキュメンテーション・コメントで使用できます。「@seeタグの検索順序」を参照してください。 2031 .sp 2032 すべてのチェック済例外がドキュメント化されるようにするために、\fI@throws\fRタグがthrows節内の例外用に存在しない場合は、\fI@throws\fRタグでドキュメント化されたかのように、\fIjavadoc\fRコマンドによって例外がHTML出力に説明なしで追加されます。 2033 .sp 2034 オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、\fI@throws\fRのドキュメントがそのメソッドからサブクラスにコピーされます。インタフェース・メソッドから実装メソッドにコピーされる場合も同様です。\fI{@inheritDoc}\fRタグを使用して、\fI@throws\fRタグがドキュメンテーションを継承するように強制できます。 2035 .RE 2036 .PP 2037 {@value \fIpackage\&.class#field\fR} 2038 .RS 4 2039 JDK 1\&.4で導入 2040 .sp 2041 定数の値を表示します。\fI{@value}\fRタグが静的フィールドのドキュメンテーション・コメントで引数なしで使用されている場合、その定数の値を表示します。 2042 .sp 2043 .if n \{\ 2044 .RS 4 2045 .\} 2046 .nf 2047 /** 2048 * The value of this constant is {@value}\&. 2049 */ 2050 public static final String SCRIPT_START = "<script>" 2051 .fi 2052 .if n \{\ 2053 .RE 2054 .\} 2055 任意のドキュメンテーション・コメント内で引数\fIpackage\&.class#field\fRありで使用された場合、\fI{@value}\fRタグは指定された定数の値を表示します。 2056 .sp 2057 .if n \{\ 2058 .RS 4 2059 .\} 2060 .nf 2061 /** 2062 * Evaluates the script starting with {@value #SCRIPT_START}\&. 2063 */ 2064 public String evalScript(String script) {} 2065 .fi 2066 .if n \{\ 2067 .RE 2068 .\} 2069 引数\fIpackage\&.class#field\fRは、\fI@see\fRタグ引数と同一の形式になります。ただし、メンバーは静的フィールドである必要があります。 2070 .sp 2071 これらの定数の値は「定数フィールド値」 2072 (http://docs\&.oracle\&.com/javase/8/docs/api/constant\-values\&.html)にも表示されます 2073 .RE 2074 .PP 2075 @version \fIversion\-text\fR 2076 .RS 4 2077 JDK 1\&.0で導入 2078 .sp 2079 \fI\-version\fRオプションが使用されている場合、生成ドキュメントに\fI「バージョン」\fR小見出しを追加して、指定された\fIversion\-text\fRの値を書き込みます。このタグはこのコードが含まれるソフトウェアの現在のリリース番号を保持するためのものであるのに対し、\fI@since\fRタグは、このコードが導入されたリリース番号を保持します。\fIversion\-text\fRの値には、特別な内部構造はありません。JavadocツールでのDocコメントの記述方法の@versionに関する項 2080 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#@version)を参照してください 2081 .sp 2082 1つのドキュメンテーション・コメントに複数の\fI@version\fRタグを含めることができます。必要に応じて、1つの\fI@version\fRタグに1つのリリース番号を指定することも、複数のリリース番号を指定することもできます。前者の場合は、\fIjavadoc\fRコマンドによって名前と名前の間にカンマ(,)と空白文字が挿入されます。後者の場合は、テキスト全体が解析されることなく、生成ドキュメントにコピーされます。したがって、カンマではなく、各言語に対応した名前区切り文字を使用する必要があるときに、1行に複数の名前を指定できます。 2083 .RE 2084 .SH "タグを使用できる場所" 2085 .PP 2086 ここでは、タグを使用できる場所について説明します。次のタグがすべてのドキュメンテーション・コメントで使用できます。\fI@see\fR、\fI@since\fR、\fI@deprecated\fR、\fI{@link}\fR、\fI{@linkplain}\fRおよび\fI{@docroot}\fR。 2087 .SS "概要タグ" 2088 .PP 2089 概要タグは、概要ページのドキュメンテーション・コメントで使用できるタグです(このドキュメンテーション・コメントは、通常overview\&.htmlという名前のソース・ファイル内にあります)。他のドキュメンテーション・コメントの場合と同様に、これらのタグは、主説明の後で使用する必要があります。 2090 .PP 2091 \fB注意:\fR 2092 Java SE 1\&.2では、概要ドキュメント内の\fI{@link}\fRタグに不具合があります。テキストは正しく表示されますが、リンクが設定されません。現在のところ、\fI{@docRoot}\fRタグは、概要ドキュメント内では機能しません。 2093 .PP 2094 概要タグは、次のとおりです。 2095 .PP 2096 @see reference || @since since\-text || @serialField field\-name field\-type field\-description || @author name\-text || @version version\-text || {@link package\&.class#member label} || {@linkplain package\&.class#member label} || {@docRoot} || 2097 .SS "パッケージ・タグ" 2098 .PP 2099 パッケージ・タグは、パッケージのドキュメンテーション・コメントで使用できるタグで、ドキュメンテーション・コメントはpackage\&.htmlまたはpackage\-info\&.javaという名前のソース・ファイル内にあります。ここで使用できる\fI@serial\fRタグは、\fIinclude\fRまたは\fIexclude\fR引数を指定したもののみです。 2100 .PP 2101 パッケージ・タグは、次のとおりです。 2102 .PP 2103 @see reference || @since since\-text || @serial field\-description | include | exclude || @author name\-text || @version version\-text || {@linkplain package\&.class#member label} || {@linkplain package\&.class#member label} || {@docRoot} || 2104 .SS "クラスおよびインタフェース・タグ" 2105 .PP 2106 次に、クラスまたはインタフェースのドキュメンテーション・コメントで使用できるタグを示します。\fI@serial\fRタグは、\fIinclude\fRまたは\fIexclude\fR引数を指定して、クラスまたはインタフェースのドキュメンテーション内でのみ使用できます。 2107 .PP 2108 @see reference || @since since\-text || @deprecated deprecated\-text || @serial field\-description | include | exclude || @author name\-text || @version version\-text || {@link package\&.class#member label} || {@linkplain package\&.class#member label} || {@docRoot} || 2109 .PP 2110 クラス・コメントの例: 2111 .sp 2112 .if n \{\ 2113 .RS 4 2114 .\} 2115 .nf 2116 /** 2117 * A class representing a window on the screen\&. 2118 * For example: 2119 * <pre> 2120 * Window win = new Window(parent); 2121 * win\&.show(); 2122 * </pre> 2123 * 2124 * @author Sami Shaio 2125 * @version 1\&.13, 06/08/06 2126 * @see java\&.awt\&.BaseWindow 2127 * @see java\&.awt\&.Button 2128 */ 2129 class Window extends BaseWindow { 2130 \&.\&.\&. 2131 } 2132 .fi 2133 .if n \{\ 2134 .RE 2135 .\} 2136 .SS "フィールド・タグ" 2137 .PP 2138 これらのタグは、フィールドに表示できます。 2139 .PP 2140 @see reference || @since since\-text || @deprecated deprecated\-text || @serial field\-description | include | exclude || @serialField field\-name field\-type field\-description || {@link package\&.class#member label} || {@linkplain package\&.class#member label} || {@docRoot} || {@value package\&.class#field} 2141 .PP 2142 フィールド・コメントの例: 2143 .sp 2144 .if n \{\ 2145 .RS 4 2146 .\} 2147 .nf 2148 /** 2149 * The X\-coordinate of the component\&. 2150 * 2151 * @see #getLocation() 2152 */ 2153 int x = 1263732; 2154 .fi 2155 .if n \{\ 2156 .RE 2157 .\} 2158 .SS "コンストラクタとメソッド・タグ" 2159 .PP 2160 次に、コンストラクタまたはメソッドのドキュメンテーション・コメントで使用できるタグを示します。ただし、\fI@return\fRはコンストラクタでは使用できず、 2161 \fI{@inheritDoc}\fRには制限があります。 2162 .PP 2163 @see reference || @since since\-text || @deprecated deprecated\-text || @param parameter\-name description || @return description || @throws class\-name description || @exception class\-name description || @serialData data\-description || {@link package\&.class#member label} || {@linkplain package\&.class#member label} || {@inheritDoc} || {@docRoot} 2164 .PP 2165 \fB注意:\fR 2166 \fI@serialData\fRタグは、\fIwriteObject\fR、\fIreadObject\fR、\fIwriteExternal\fR、\fIreadExternal\fR、\fIwriteReplace\fRおよび\fIreadResolve\fRメソッドのドキュメンテーション・コメントでのみ使用できます。 2167 .PP 2168 メソッド・コメントの例: 2169 .sp 2170 .if n \{\ 2171 .RS 4 2172 .\} 2173 .nf 2174 /** 2175 * Returns the character at the specified index\&. An index 2176 * ranges from <code>0</code> to <code>length() \- 1</code> 2177 * 2178 * @param index the index of the desired character\&. 2179 * @return the desired character\&. 2180 * @exception StringIndexOutOfRangeException 2181 * if the index is not in the range <code>0</code> 2182 * to <code>length()\-1</code> 2183 * @see java\&.lang\&.Character#charValue() 2184 */ 2185 public char charAt(int index) { 2186 \&.\&.\&. 2187 } 2188 .fi 2189 .if n \{\ 2190 .RE 2191 .\} 2192 .SH "オプション" 2193 .PP 2194 \fIjavadoc\fRコマンドは、ドックレットを使用して出力を決定します。\fIjavadoc\fRコマンドは、\fI\-doclet\fRオプションでカスタム・ドックレットが指定されている場合以外は、デフォルトの標準ドックレットを使用します。\fIjavadoc\fRコマンドには、任意のドックレットとともに使用できるコマンドライン・オプションがあります。これらのオプションについては、Javadocオプションで説明します。標準ドックレットでは、この他に、いくつかの追加のコマンドライン・オプションが提供されます。これらのオプションについては、標準ドックレットのオプションで説明します。どのオプション名も、大文字と小文字が区別されません。ただし、オプションの引数では、大文字と小文字が区別されます。 2195 .sp 2196 .RS 4 2197 .ie n \{\ 2198 \h'-04'\(bu\h'+03'\c 2199 .\} 2200 .el \{\ 2201 .sp -1 2202 .IP \(bu 2.3 2203 .\} 2204 Javadocオプションも参照してください 2205 .RE 2206 .sp 2207 .RS 4 2208 .ie n \{\ 2209 \h'-04'\(bu\h'+03'\c 2210 .\} 2211 .el \{\ 2212 .sp -1 2213 .IP \(bu 2.3 2214 .\} 2215 標準ドックレットのオプションも参照してください 2216 .RE 2217 .PP 2218 オプションは次のとおりです。 2219 .PP 2220 \-1\&.1 || \-author || \-bootclasspath classpathlist || \-bottom text || \-breakiterator || \-charset name || \-classpath classpathlist || \-d directory || \-docencoding name || \-docfilesubdirs || \-doclet class || \-docletpath classpathlist || \-doctitle title || \-encoding || \-exclude packagename1:packagename2:\&.\&.\&. || \-excludedocfilessubdir name1:name2 || \-extdirs dirist || \-footer footer || \-group groupheading packagepattern:packagepattern || \-header header || \-help || \-helpfile path\efilename || \-Jflag || \-keywords || \-link extdocURL || \-linkoffline extdocURL packagelistLoc || \-linksource || \-locale language_country_variant || \-nocomment || \-nodeprecated || \-nodeprecatedlist || \-nohelp || \-noindex || \-nonavbar || \-noqualifier all | packagename1:packagename2\&.\&.\&. || \-nosince || \-notimestamp || \-notree || 2221 \fI\-overview path/filename || \fR\-package || \-private || \-protected || \-public || \-quiet || \-serialwarn || \-source release || \-sourcepath sourcepathlist || \-sourcetab tablength || \-splitindex || 2222 \fI\-stylesheet path/filename || \fR\-subpackages package1:package2:\&.\&.\&. || \-tag tagname:Xaoptcmf:"taghead" || \-taglet class || \-tagletpath tagletpathlist || \-title title || \-top || \-use || \-verbose || \-version || \-windowtitle title 2223 .PP 2224 次のオプションは、すべてのドックレットに使用可能なコアのJavadocオプションです。標準ドックレットでは、ドックレットの他の部分を提供します。\fI\-bootclasspath\fR、\fI\-breakiterator\fR、\fI\-classpath\fR、\fI\-doclet\fR、\fI\-docletpath\fR、\fI\-encoding\fR、\-\fIexclude\fR、\fI\-extdirs\fR、\fI\-help\fR、\fI\-locale\fR、\fI\-\fR\fIoverview\fR、\fI\-package\fR、\fI\-private\fR、\fI\-protected\fR、\fI\-public\fR、\fI\-quiet\fR、\fI\-source\fR、\fI\-sourcepath\fR、\fI\-subpackages\fRおよび\fI\-verbose\fR。 2225 .SS "Javadocオプション" 2226 .PP 2227 \-overview \fIpath/filename \fR 2228 .RS 4 2229 2230 \fIjavadoc\fRコマンドに対して、\fIpath/filename \fRで指定されたソース・ファイルから概要ドキュメント用のテキストを取得し、そのテキストを概要ページ(overview\-summary\&.html)に配置するように指定します。\fIpath/filename\fRは、現在のディレクトリからの相対パスです。 2231 .sp 2232 \fIfilename\fRの値で任意の名前を使用し、pathで任意の配置先を指定できますが、通常はoverview\&.htmlという名前を付け、ソース・ツリー内の最上位パッケージ・ディレクトリを含むディレクトリに配置します。この場所に配置すると、パッケージをドキュメント化するときにpathを指定する必要がなくなります。これは、\fI\-sourcepath\fRオプションによってこのファイルが指し示されるからです。 2233 .sp 2234 たとえば、\fIjava\&.lang\fRパッケージのソース・ツリーが/src/classes/java/lang/の場合、概要ファイルを/src/classes/overview\&.htmlに配置できます 2235 .sp 2236 実際の例を参照してください。 2237 .sp 2238 \fIpath/filename\fRで指定するファイルについては、概要コメント・ファイルを参照してください。 2239 .sp 2240 概要ページが作成されるのは、\fIjavadoc\fRコマンドに複数のパッケージ名を渡した場合のみです。詳細は、HTMLフレームを参照してください。概要ページのタイトルは、\fI\-doctitle\fRによって設定されます。 2241 .RE 2242 .PP 2243 \-Xdoclint:(all|none|[\-]\fI<group>\fR) 2244 .RS 4 2245 不正な参照、アクセシビリティの欠落およびJavadocコメントの不足の警告をレポートし、無効なJavadoc構文および不足しているHTMLタグのエラーをレポートします。 2246 .sp 2247 このオプションにより、\fIjavadoc\fRコマンドは生成された出力に含まれるすべてのドキュメント・コメントをチェックします。通常どおり、標準オプション\fI\-public\fR、\fI\-protected\fR、\fI\-package\fRおよび\fI\-private\fRで生成された出力に含む項目を選択できます。 2248 .sp 2249 \fI\-Xdoclint\fRが有効になっている場合は、\fIjavac\fRコマンドと同様にメッセージで問題がレポートされます。\fIjavadoc\fRコマンドは、メッセージ、ソース・ファイルのコピーおよびエラーが検出された正確な位置を指すキャレットを出力します。メッセージは、重大度、および生成されたドキュメントがバリデータを使用して実行された場合にエラーが発生する可能性に応じて、警告またはエラーになります。たとえば、不正な参照またはJavadocコメントの欠落は、\fIjavadoc\fRコマンドが無効なHTMLを生成する原因にならないため、これらの問題は警告としてレポートされます。構文エラーまたはHTML終了タグの欠落は、\fIjavadoc\fRコマンドが無効なHTMLを生成する原因になるため、これらの問題はエラーとしてレポートされます。 2250 .sp 2251 デフォルトでは、\fI\-Xdoclint\fRオプションは有効になっています。オプション\fI\-Xdoclint:none\fRで無効にします。 2252 .sp 2253 \fI\-Xdoclint\fRオプションでレポートされる内容は次のオプションで変更します。 2254 .sp 2255 .RS 4 2256 .ie n \{\ 2257 \h'-04'\(bu\h'+03'\c 2258 .\} 2259 .el \{\ 2260 .sp -1 2261 .IP \(bu 2.3 2262 .\} 2263 \fI\-Xdoclint\fR\fI\fR\fI none\fR: 2264 \fI\-Xdoclint\fRオプションを無効にします。 2265 .RE 2266 .sp 2267 .RS 4 2268 .ie n \{\ 2269 \h'-04'\(bu\h'+03'\c 2270 .\} 2271 .el \{\ 2272 .sp -1 2273 .IP \(bu 2.3 2274 .\} 2275 \fI\-Xdoclint\fR\fI\fR\fI \fR\fIgroup\fR: 2276 \fIgroup\fRチェックを有効にします。 2277 .RE 2278 .sp 2279 .RS 4 2280 .ie n \{\ 2281 \h'-04'\(bu\h'+03'\c 2282 .\} 2283 .el \{\ 2284 .sp -1 2285 .IP \(bu 2.3 2286 .\} 2287 \fI\-Xdoclint\fR\fI\fR\fI all\fR: すべてのチェック・グループを有効にします。 2288 .RE 2289 .sp 2290 .RS 4 2291 .ie n \{\ 2292 \h'-04'\(bu\h'+03'\c 2293 .\} 2294 .el \{\ 2295 .sp -1 2296 .IP \(bu 2.3 2297 .\} 2298 \fI\-Xdoclint\fR\fI\fR\fI all,\fR\fI\-group\fR: 2299 \fIgroup\fRチェック以外のすべてを有効にします。 2300 .RE 2301 .sp 2302 変数\fIgroup\fRは次のいずれかの値を持ちます。 2303 .sp 2304 .RS 4 2305 .ie n \{\ 2306 \h'-04'\(bu\h'+03'\c 2307 .\} 2308 .el \{\ 2309 .sp -1 2310 .IP \(bu 2.3 2311 .\} 2312 \fIaccessibility\fR: アクセシビリティ・チェッカで検出する問題をチェックします(たとえば、\fI<table>\fRタグで指定されるno captionまたはsummary属性)。 2313 .RE 2314 .sp 2315 .RS 4 2316 .ie n \{\ 2317 \h'-04'\(bu\h'+03'\c 2318 .\} 2319 .el \{\ 2320 .sp -1 2321 .IP \(bu 2.3 2322 .\} 2323 \fIhtml\fR: インライン要素へのブロック要素の挿入や終了タグを必要とする要素を終了しないなど、上位レベルHTMLの問題を検出します。ルールは、HTML 4\&.01仕様から導出されます。このタイプのチェックは、\fIjavadoc\fRコマンドを有効にして、ブラウザが受け入れる可能性のあるHTMLの問題を検出します。 2324 .RE 2325 .sp 2326 .RS 4 2327 .ie n \{\ 2328 \h'-04'\(bu\h'+03'\c 2329 .\} 2330 .el \{\ 2331 .sp -1 2332 .IP \(bu 2.3 2333 .\} 2334 \fImissing\fR: 欠落しているJavadocコメントまたはタグをチェックします(たとえば、欠落しているコメントやクラス、または欠落している\fI@return\fRタグやメソッド上の同様のタグ)。 2335 .RE 2336 .sp 2337 .RS 4 2338 .ie n \{\ 2339 \h'-04'\(bu\h'+03'\c 2340 .\} 2341 .el \{\ 2342 .sp -1 2343 .IP \(bu 2.3 2344 .\} 2345 \fIreference\fR: JavadocタグのJava API要素の参照に関連する問題をチェックします(たとえば、\fI@see\fRで見つからない項目、または\fI@param\fRの後の不正な名前)。 2346 .RE 2347 .sp 2348 .RS 4 2349 .ie n \{\ 2350 \h'-04'\(bu\h'+03'\c 2351 .\} 2352 .el \{\ 2353 .sp -1 2354 .IP \(bu 2.3 2355 .\} 2356 \fIsyntax\fR: エスケープされていない山カッコ(\fI<\fRおよび\fI>\fR)やアンパサンド(\fI&\fR)、無効なJavadocタグなどの下位レベルの問題を確認します。 2357 .RE 2358 .sp 2359 \fI\-Xdoclint\fRオプションを複数回指定して、複数のカテゴリのエラーと警告をチェックするオプションを有効にできます。または、前のオプションを使用して、複数のエラーおよび警告カテゴリを指定できます。たとえば、次のコマンドのいずれかを使用して、\fIfilename\fRファイル内のHTML、構文およびアクセシビリティの問題をチェックします。 2360 .sp 2361 .if n \{\ 2362 .RS 4 2363 .\} 2364 .nf 2365 javadoc \-Xdoclint:html \-Xdoclint:syntax \-Xdoclint:accessibility \fIfilename\fR 2366 javadoc \-Xdoclint:html,syntax,accessibility \fIfilename\fR 2367 .fi 2368 .if n \{\ 2369 .RE 2370 .\} 2371 \fB注意:\fR 2372 \fIjavadoc\fRコマンドでは、これらのチェックの完全性は保証されません。具体的には、完全なHTMLコンプライアンス・チェッカではありません。\-\fIXdoclint\fRオプションの目的は、\fIjavadoc\fRコマンドを有効にして一般的なエラーの大半をレポートすることです。 2373 .sp 2374 \fIjavadoc\fRコマンドは、無効な入力の修正を試行せず、レポートのみ行います。 2375 .RE 2376 .PP 2377 \-public 2378 .RS 4 2379 publicクラスおよびメンバーのみ表示します。 2380 .RE 2381 .PP 2382 \-protected 2383 .RS 4 2384 protectedおよびpublicのクラスとメンバーのみを表示します。これがデフォルトです。 2385 .RE 2386 .PP 2387 \-package 2388 .RS 4 2389 package、protected、およびpublicのクラスとメンバーのみ表示します。 2390 .RE 2391 .PP 2392 \-private 2393 .RS 4 2394 すべてのクラスとメンバーを表示します。 2395 .RE 2396 .PP 2397 \-help 2398 .RS 4 2399 オンライン・ヘルプを表示します。\fIjavadoc\fRと\fIドックレット\fRのコマンドライン・オプションがリストされます。 2400 .RE 2401 .PP 2402 \-doclet \fIclass\fR 2403 .RS 4 2404 ドキュメントの生成に使用するドックレットを起動するためのクラス・ファイルを指定します。完全修飾名を使用します。このドックレットにより、出力の内容と形式が定義されます。\fI\-doclet\fRオプションが使用されていない場合、\fIjavadoc\fRコマンドは、標準ドックレットを使用してデフォルトのHTML形式を生成します。このクラスには\fIstart(Root)\fRメソッドが含まれている必要があります。この起動クラスへのパスは\fI\-docletpath\fRオプションによって定義されます。ドックレットの概要 2405 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/doclet/overview\&.html)を参照してください 2406 .RE 2407 .PP 2408 \-docletpath \fIclasspathlist\fR 2409 .RS 4 2410 \fI\-doclet\fRオプションで指定されたドックレット開始クラス・ファイル、およびそのクラスが依存するすべてのJARファイルへのパスを指定します。開始クラス・ファイルがJARファイル内にある場合、このオプションでJARファイルへのパスを指定します。絶対パスまたは現在のディレクトリからの相対パスを指定できます。\fIclasspathlist\fRに複数のパスやJARファイルが含まれる場合には、それらをSolarisの場合はコロン(:)で、Windowsの場合はセミコロン(;)でそれぞれ区切ります。目的のドックレット開始クラスがすでに検索パス内にある場合は、このオプションは不要です。ドックレットの概要 2411 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/doclet/overview\&.html)を参照してください 2412 .RE 2413 .PP 2414 \-1\&.1 2415 .RS 4 2416 Javadoc 1\&.4から削除され、代替はありません。このオプションは、Javadoc 1\&.1によって生成されるのと同じ外見と機能を持つドキュメントを作成するためのものでした(ネストされたクラスはサポートされていません)。このオプションが必要な場合は、Javadoc 1\&.2または1\&.3をかわりに使用してください。 2417 .RE 2418 .PP 2419 \-source \fIrelease\fR 2420 .RS 4 2421 受け付けるソース・コードのリリースを指定します。\fIrelease\fRパラメータには次の値を指定できます。\fIjavac\fRコマンドでコードをコンパイルするときに使用する値に対応する\fIリリース\fRの値を使用します。 2422 .sp 2423 .RS 4 2424 .ie n \{\ 2425 \h'-04'\(bu\h'+03'\c 2426 .\} 2427 .el \{\ 2428 .sp -1 2429 .IP \(bu 2.3 2430 .\} 2431 \fBリリース値: 1\&.5\fR。\fIjavadoc\fRコマンドは、JDK 1\&.5で導入された総称および他の言語機能を含むコードを受け付けます。\fI\-source\fRオプションが使用されなかった場合のコンパイラのデフォルト動作は、1\&.5のものになります。 2432 .RE 2433 .sp 2434 .RS 4 2435 .ie n \{\ 2436 \h'-04'\(bu\h'+03'\c 2437 .\} 2438 .el \{\ 2439 .sp -1 2440 .IP \(bu 2.3 2441 .\} 2442 \fBリリース値: 1\&.4\fR。\fIjavadoc\fRコマンドは、JDK 1\&.4で導入されたアサーションを含むコードを受け付けます。 2443 .RE 2444 .sp 2445 .RS 4 2446 .ie n \{\ 2447 \h'-04'\(bu\h'+03'\c 2448 .\} 2449 .el \{\ 2450 .sp -1 2451 .IP \(bu 2.3 2452 .\} 2453 \fBリリース値: 1\&.3\fR。\fIjavadoc\fRコマンドは、JDK 1\&.3以降に導入されたアサーション、総称、または他の言語機能をサポートしません。 2454 .RE 2455 .RE 2456 .PP 2457 \-sourcepath \fIsourcepathlist\fR 2458 .RS 4 2459 パッケージ名または\fI\-subpackages\fRオプションを\fIjavadoc\fRコマンドに渡すときに、ソース・ファイルを見つけるための検索パスを指定します。 2460 \fI複数のパスはコロン(:)で区切ります。\fR\fIjavadoc\fRコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。このオプションを使用して、ドキュメント化されるソース・ファイルの位置のみでなく、それ自体はドキュメント化されないがドキュメント化されるソース・ファイルから継承されたコメントを持つソース・ファイルの位置も確認できます。 2461 .sp 2462 \fI\-sourcepath\fRオプションを使用できるのは、\fIjavadoc\fRコマンドにパッケージ名を渡す場合のみです。\fIjavadoc\fRコマンドに渡されるソース・ファイルは検索されません。ソース・ファイルを特定するには、そのディレクトリに移動するか、「1つ以上のクラスのドキュメント化」に示すように各ファイルの前にパスを含めます。\fI\-sourcepath\fRが省略された場合、\fIjavadoc\fRコマンドは、クラス・パスを使用してソース・ファイルを検索します(\fI\-classpath\fRを参照)。デフォルトの\fI\-sourcepath\fRは、クラス・パスの値です。\fI\-classpath\fRを省略してパッケージ名を\fIjavadoc\fRコマンドに渡すと、\fIjavadoc\fRコマンドは現在のディレクトリ(およびそのサブディレクトリ)からソース・ファイルを検索します。 2463 .sp 2464 \fIsourcepathlist\fRには、ドキュメント化するパッケージのソース・ツリーのルート・ディレクトリを設定します。 2465 .sp 2466 たとえば、\fIcom\&.mypackage\fRという名前のパッケージをドキュメント化する場合に、そのソース・ファイルが/home/user/src/com/mypackage/*\&.javaにあるとします。ソース・パスをcom\emypackageが含まれるディレクトリ/home/user/srcに指定してから、次のように、パッケージ名を指定します。 2467 .sp 2468 .if n \{\ 2469 .RS 4 2470 .\} 2471 .nf 2472 javadoc \-sourcepath /home/user/src/ com\&.mypackage 2473 .fi 2474 .if n \{\ 2475 .RE 2476 .\} 2477 ソース・パスの値とパッケージ名を連結して、ドットをスラッシュ(/)に変更すると、次のように、パッケージのフルパスになります。 2478 .sp 2479 /home/user/src/com/mypackage 2480 .sp 2481 2つのソース・パスを設定するには、次のようにします。 2482 .sp 2483 .if n \{\ 2484 .RS 4 2485 .\} 2486 .nf 2487 javadoc \-sourcepath /home/user1/src:/home/user2/src com\&.mypackage 2488 .fi 2489 .if n \{\ 2490 .RE 2491 .\} 2492 .RE 2493 .PP 2494 \-classpath \fIclasspathlist\fR 2495 .RS 4 2496 \fIjavadoc\fRコマンドが参照クラスの検索を行うときに使用するパスを指定します。参照クラスとは、ドキュメント化されるクラスと、それらのクラスによって参照されるすべてのクラスのことです。 2497 \fI複数のパスはコロン(:)で区切ります。\fR\fIjavadoc\fRコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。\fIclasspathlist\fRの値を指定するときは、クラス・パスのドキュメントにある指示に従ってください。 2498 .sp 2499 \fI\-sourcepath\fRが省略された場合、\fIjavadoc\fRコマンドは\fI\-classpath\fRを使用して、ソース・ファイルおよびクラス・ファイルを検索します(下位互換性のため)。ソース・ファイルとクラス・ファイルを別々のパスから検索する必要がある場合は、\fI\-sourcepath\fRと\fI\-classpath\fRの両方を使用します。 2500 .sp 2501 たとえば、\fIcom\&.mypackage\fRをドキュメント化する場合に、そのソース・ファイルがディレクトリ/home/user/src/com/mypackageにあり、このパッケージが/home/user/libthen内のライブラリに依存しているとき、次のように指定します。 2502 .sp 2503 .if n \{\ 2504 .RS 4 2505 .\} 2506 .nf 2507 javadoc \-sourcepath /home/user/lib \-classpath /home/user/src com\&.mypackage 2508 .fi 2509 .if n \{\ 2510 .RE 2511 .\} 2512 他のツールと同様に、\fI\-classpath\fRが指定されていない場合、\fICLASSPATH\fR環境変数が設定されていれば、\fIjavadoc\fRコマンドはその環境変数を使用します。どちらも設定されていない場合、\fIjavadoc\fRコマンドは現在のディレクトリからクラスを検索します。 2513 .sp 2514 \fIjavadoc\fRコマンドが\fI\-classpath\fRを使用してユーザー・クラスを検索する方法についての、拡張機能クラスやブートストラップ・クラスに関連した詳細は、クラスの検索方法 2515 (http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html)を参照してください。 2516 .sp 2517 *のベース名を含むクラス・パス要素は、\fI\&.jar\fRまたは\fI\&.JAR\fRを拡張子に持つディレクトリ内のすべてのファイルのリストを指定するのと同等とみなされます。 2518 .sp 2519 たとえば、ディレクトリ\fImydir\fRに\fIa\&.jar\fRと\fIb\&.JA\fRRが含まれている場合、クラス・パス要素\fIfoo/*\fRは\fIA\&.jar:b\&.JAR\fRに展開されますが、JARファイルの順番は未指定となります。非表示のファイルを含む、指定したディレクトリ内のすべてのJARファイルがリストに含まれます。*からなるクラス・パス・エントリは、現在のディレクトリ内のすべてのJARファイルのリストに展開されます。\fICLASSPATH\fR環境変数も同様に展開されます。クラス・パスのワイルドカードの展開は、Java仮想マシン(JVM)の開始前に行われます。Javaプログラムは、System\&.getenv(\fI"CLASSPATH"\fR)の呼び出しによってなど、環境を問い合せる場合を除き、展開されていないワイルドカードを参照しません。 2520 .RE 2521 .PP 2522 \-subpackages \fIpackage1:package2:\&.\&.\&.\fR 2523 .RS 4 2524 ソース・ファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソース・コードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージが自動的に組み込まれるからです。各package引数は、任意の最上位サブパッケージ(\fIjava\fRなど)または完全修飾パッケージ(\fIjavax\&.swing\fRなど)になります。ソース・ファイルを含める必要はありません。引数は、すべてのオペレーティング・システムで、コロンで区切られます。ワイルドカードは使用できません。パッケージの検索場所を指定するには、\fI\-sourcepath\fRを使用します。このオプションでは、ソース・ツリー内に存在するがパッケージに含まれないソース・ファイルを処理しません。ソース・ファイルの処理を参照してください。 2525 .sp 2526 たとえば、次のコマンドは、\fIjava\fRおよび\fIjavax\&.swing\fRという名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。 2527 .sp 2528 .if n \{\ 2529 .RS 4 2530 .\} 2531 .nf 2532 javadoc \-d docs \-sourcepath /home/user/src \-subpackages java:javax\&.swing 2533 .fi 2534 .if n \{\ 2535 .RE 2536 .\} 2537 .RE 2538 .PP 2539 \-exclude \fIpackagename1:packagename2:\&.\&.\&.\fR 2540 .RS 4 2541 指定されたパッケージとそのサブパッケージを\fI\-subpackages\fRによって作成されたリストから無条件に除外します。過去または将来の\fI\-subpackages\fRオプションの指定によって組み込まれるパッケージも除外の対象となります。 2542 .sp 2543 次の例では、\fIjava\&.io\fR、\fIjava\&.util\fR、\fIjava\&.math\fRなどは組み込まれますが、\fIjava\&.net\fRと\fIjava\&.lang\fRをルートに持つパッケージは除外されます。\fIjava\&.lang\fRのサブパッケージである\fIjava\&.lang\&.ref\fRが除外される点に注意してください。 2544 .sp 2545 .if n \{\ 2546 .RS 4 2547 .\} 2548 .nf 2549 javadoc \-sourcepath /home/user/src \-subpackages java \-exclude 2550 java\&.net:java\&.lang 2551 .fi 2552 .if n \{\ 2553 .RE 2554 .\} 2555 .RE 2556 .PP 2557 \-bootclasspath \fIclasspathlist\fR 2558 .RS 4 2559 ブート・クラスが存在するパスを指定します。ブート・クラスとは、通常、Javaプラットフォーム・クラスのことです。\fIbootclasspath\fRは、\fIjavadoc\fRコマンドがソース・ファイルとクラス・ファイルを探すときに使用する検索パスの一部です。詳細は、クラスの検出方法 2560 (http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html)を参照してください 2561 .sp 2562 \fIclasspathlist\fRパラメータ内のディレクトリは、セミコロン(;)で区切る(Windowsの場合)か、コロン(:)で区切ります(Oracle Solarisの場合)。 2563 .RE 2564 .PP 2565 \-extdirs \fIdirist\fR 2566 .RS 4 2567 拡張機能クラスが存在するディレクトリを指定します。拡張機能クラスとは、Java拡張機能機構を使用するすべてのクラスです。\fIextdirs\fRオプションは、\fIjavadoc\fRコマンドがソース・ファイルとクラス・ファイルを探すときに使用する検索パスの一部です。詳細は、\fI\-classpath\fRオプションを参照してください。\fIdirlist\fR内のディレクトリは、セミコロン(;)で区切る(Windowsの場合)か、コロン(:)で区切ります(Oracle Solarisの場合)。 2568 .RE 2569 .PP 2570 \-verbose 2571 .RS 4 2572 \fIjavadoc\fRコマンドの実行中に詳細なメッセージを表示します。\fIverbose\fRオプションを指定しないと、ソース・ファイルのロード時、ドキュメントの生成時(ソース・ファイルごとに1つのメッセージ)、およびソート時にメッセージが表示されます。verboseオプションを指定すると、各Javaソース・ファイルの解析に要した時間(ミリ秒単位)を示す追加のメッセージが表示されます。 2573 .RE 2574 .PP 2575 \-quiet 2576 .RS 4 2577 メッセージを抑制し、警告とエラーのみが表示されるようにして、これらを確認しやすくします。\fIversion\fR文字列も抑止します。 2578 .RE 2579 .PP 2580 \-breakiterator 2581 .RS 4 2582 英語の場合、パッケージ、クラスまたはメンバーの主説明の最初の文の終わりを判断する際に、\fIjava\&.text\&.BreakIterator\fRの国際化された文境界を使用します。他のすべてのロケールは、英語言語というロケール固有のアルゴリズムではなく、すでに\fIBreakIterator\fRクラスを使用しています。最初の文は、パッケージ、クラス、またはメンバーのサマリーにコピーされ、アルファベット順の索引にコピーされます。JDK 1\&.2以降、\fIBreakIterator\fRクラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、\fI\-breakiterator\fRオプションは、1\&.2以降では英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。 2583 .sp 2584 .RS 4 2585 .ie n \{\ 2586 \h'-04'\(bu\h'+03'\c 2587 .\} 2588 .el \{\ 2589 .sp -1 2590 .IP \(bu 2.3 2591 .\} 2592 英文のデフォルトの文区切りアルゴリズム。空白文字またはHTMLブロック・タグ(\fI<P>\fRなど)が続くピリオドで停止します。 2593 .RE 2594 .sp 2595 .RS 4 2596 .ie n \{\ 2597 \h'-04'\(bu\h'+03'\c 2598 .\} 2599 .el \{\ 2600 .sp -1 2601 .IP \(bu 2.3 2602 .\} 2603 breakiterator文区切りアルゴリズム。次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止します。このアルゴリズムでは「The serial no\&. is valid」など、ほとんどの省略表記が処理されますが、「Mr\&. Smith」は処理されません。\fI\-breakiterator\fRオプションでは、HTMLタグや、数字または記号で始まる文では停止しません。HTMLタグに埋め込まれている場合でも、「\&.\&./filename」の最後のピリオドで停止します。 2604 .RE 2605 .sp 2606 Java SE 1\&.5では\fI\-breakiterator\fR警告メッセージが削除され、デフォルトの文区切りアルゴリズムは変更されていません。ソース・コードを変更せず、SE 1\&.4\&.xでの\fI\-breakiterator\fRオプションの警告を除去していない場合でも、何もする必要はありません。Java SE 1\&.5\&.0からは警告は消滅しています。 2607 .RE 2608 .PP 2609 \-locale \fIlanguage_country_variant\fR 2610 .RS 4 2611 \fIjavadoc\fRコマンドがドキュメントを生成するときに使用するロケールを指定します。この引数は、\fIj\fR\fIava\&.util\&.Locale\fRドキュメントで説明しているように、\fIen_US\fR 2612 (英語、米国)または\fIen_US_WIN\fR 2613 (Windowsバリアント)などのロケールの名前です。 2614 .sp 2615 \fB注意:\fR 2616 \fI\-locale\fRオプションは、標準ドックレットが提供するすべてのオプション、またはその他の任意のドックレットが提供するすべてのオプションより前(左側)に指定する必要があります。そうしないと、ナビゲーション・バーが英語で表示されます。このコマンドライン・オプションのみ、指定する順序に依存します。標準ドックレットのオプションを参照してください。 2617 .sp 2618 ロケールを指定すると、指定したロケールのリソース・ファイルが\fIjavadoc\fRコマンドによって選択されて、メッセージ(ナビゲーション・バー、リストと表の見出し、ヘルプ・ファイルの目次、stylesheet\&.cssのコメントなどの文字列)のために使用されます。また、アルファベット順にソートされるリストのソート順、および最初の文の終わりを判断するための文の区切り文字も、指定したロケールによって決まります。\fI\-locale\fRオプションは、ドキュメント化されるクラスのソース・ファイル内で指定されているドキュメンテーション・コメントのテキストのロケールを決定するものではありません。 2619 .RE 2620 .PP 2621 \-encoding 2622 .RS 4 2623 ソース・ファイルのエンコーディングの名前(\fIEUCJIS/SJIS\fRなど)を指定します。このオプションが指定されていない場合は、プラットフォームのデフォルト・コンバータが使用されます。およびオプションも参照してください。 2624 .RE 2625 .PP 2626 \-J\fIflag\fR 2627 .RS 4 2628 \fIjavadoc\fRコマンドを実行するJava Runtime Environment (JRE)に、\fIflag\fRを直接渡します。たとえば、生成ドキュメントを処理するためにシステムで32MBのメモリーを確保しておく必要がある場合は、\fI\-Xmx\fRオプションを次のように呼び出します。\fIjavadoc \-J\-Xmx32m \-J\-Xms32m com\&.mypackage\fR。\fI\-Xms\fRは省略可能で、これは初期メモリーのサイズを設定するのみのオプションで、必要なメモリーの最小量がわかっている場合に便利です。 2629 .sp 2630 \fIJ\fRと\fIflag\fRの間に空白文字はありません。 2631 .sp 2632 使用している\fIjavadoc\fRコマンドのバージョンを確認するには\fI\-version\fRオプションを使用します。出力ストリームには標準ドックレットのバージョン番号が含まれます。Javadocコマンドの実行を参照してください。 2633 .sp 2634 .if n \{\ 2635 .RS 4 2636 .\} 2637 .nf 2638 javadoc \-J\-version 2639 java version "1\&.7\&.0_09" 2640 Java(TM) SE Runtime Environment (build 1\&.7\&.0_09\-b05) 2641 Java HotSpot(TM) 64\-Bit Server VM (build 23\&.5\-b02, mixed mode) 2642 .fi 2643 .if n \{\ 2644 .RE 2645 .\} 2646 .RE 2647 .SS "標準ドックレットのオプション" 2648 .PP 2649 \-d \fIdirectory\fR 2650 .RS 4 2651 \fIjavadoc\fRコマンドが生成されたHTMLファイルを保存する生成先ディレクトリを指定します。\fI\-d\fRオプションを省略すると、ファイルは現在のディレクトリに保存されます。\fIdirectory\fRの値には、絶対ディレクトリ、または現在の作業ディレクトリからの相対ディレクトリを指定できます。Java SE 1\&.4では、\fIjavadoc\fRコマンドを実行すると生成先ディレクトリが自動的に作成されます。 2652 .sp 2653 たとえば、次の例では、\fIcom\&.mypackage\fRパッケージのドキュメントが生成され、その結果が\fI/user/doc/ \fRディレクトリに保存されます。\fIjavadoc \-d \fR\fI/user/doc/ \fR\fIcom\&.mypackage\fR 2654 .RE 2655 .PP 2656 \-use 2657 .RS 4 2658 ドキュメント化されるクラスおよびパッケージごとに1つの使用ページを組み込みます。このページには、その特定のクラスまたはパッケージのAPIを使用しているパッケージ、クラス、メソッド、コンストラクタ、およびフィールドが記述されます。たとえば、クラスCを例にとると、クラスCを使用しているものとしては、Cのサブクラス、Cとして宣言されているフィールド、Cを返すメソッド、および型Cのパラメータを持つメソッドとコンストラクタがあります。たとえば、\fIString\fR型用の使用ページを表示できます。\fIjava\&.awt\&.Font\fRクラスの\fIgetName\fRメソッドは\fIString\fR型を戻すので、\fIgetName\fRメソッドは\fIString\fRを使用し、\fIgetName\fRメソッドが\fIString\fR用の使用ページに表示されます。これは実装ではなくAPIの使用のみをドキュメント化します。メソッドがその実装で\fIString\fRを使用するが、引数として文字列を取らない、または文字列を返さない場合、それは\fIString\fRの使用とはみなされません。生成された使用ページにアクセスするには、クラスまたはパッケージに移動し、ナビゲーション・バーの\fBリンクの使用\fRをクリックします。 2659 .RE 2660 .PP 2661 \-version 2662 .RS 4 2663 生成ドキュメントに、@versionのテキストを組み込みます。このテキストは、デフォルトでは省略されます。使用している\fIjavadoc\fRコマンドのバージョンを確認するには\fI\-J\-version\fRオプションを使用します。 2664 .RE 2665 .PP 2666 \-author 2667 .RS 4 2668 生成ドキュメントに、\fI@author\fRのテキストを組み込みます。 2669 .RE 2670 .PP 2671 \-splitindex 2672 .RS 4 2673 索引ファイルをアルファベットごとに複数のファイルに分割し、文字ごとに1つのファイルと、アルファベット以外の記号で始まる索引エントリ用に1つのファイルを作成します。 2674 .RE 2675 .PP 2676 \-windowtitle \fItitle\fR 2677 .RS 4 2678 HTMLの\fI<title>\fRタグに配置するタイトルを指定します。\fItitle\fRタグに指定したテキストは、ウィンドウのタイトルや、このページに対して作成されたブラウザのブックマーク(お気に入り)に表示されます。このタイトルにはHTMLタグを含めないでください。タイトルにHTMLタグが含まれていると、ブラウザがタグを正しく解釈できません。\fItitle\fRタグ内の内部の二重引用符はエスケープ文字を使用してマークします。\fI\-windowtitle\fRオプションを省略すると、\fIjavadoc\fRコマンドは、\fI\-windowtitle\fRオプションのかわりに、\fI\-doctitle\fRオプションの値を使用します。たとえば、\fIjavadoc \-windowtitle "Java SE Platform" com\&.mypackage\fRです。 2679 .RE 2680 .PP 2681 \-doctitle \fItitle\fR 2682 .RS 4 2683 概要サマリー・ファイルの最上部の近くに配置するタイトルを指定します。\fItitle\fRタグに指定したテキストは中央揃えになり、レベル1の見出しとして、上部ナビゲーション・バーのすぐ下に置かれます。\fItitle\fRタグにはHTMLタグおよび空白文字を含めることができますが、その場合、タイトルを引用符で囲む必要があります。\fItitle\fRタグの内部で引用符を使用する場合は、エスケープする必要があります。たとえば、\fIjavadoc \-header "<b>Java Platform </b><br>v1\&.4" com\&.mypackage\fRです。 2684 .RE 2685 .PP 2686 \-title \fItitle\fR 2687 .RS 4 2688 すでに存在しません。Javadoc 1\&.2のベータ版にしか存在していませんでした。このオプションは、\fI\-doctitle\fRという名前に変更されました。名前を変更した理由は、このオプションが、ウィンドウのタイトルではなくドキュメントのタイトルを定義することを明確にするためです。 2689 .RE 2690 .PP 2691 \-header \fIheader\fR 2692 .RS 4 2693 各出力ファイルの最上部に配置するヘッダー・テキストを指定します。ヘッダーは、ナビゲーション・バーの右上に配置されます。\fIheader\fRにはHTMLタグおよび空白文字を含めることができますが、その場合、\fIheader\fRを引用符で囲む必要があります。ヘッダー内部の引用符にはエスケープ文字を使用します。たとえば、\fIjavadoc \-header "<b>Java Platform </b><br>v1\&.4" com\&.mypackage\fRです。 2694 .RE 2695 .PP 2696 \-footer \fIfooter\fR 2697 .RS 4 2698 各出力ファイルの最下部に配置するフッター・テキストを指定します。\fIfooter\fRの値は、ナビゲーション・バーの右下に配置されます。\fIfooter\fRにはHTMLタグおよび空白文字を含めることができますが、その場合、\fIfooter\fRを引用符で囲む必要があります。フッター内部の引用符にはエスケープ文字を使用します。 2699 .RE 2700 .PP 2701 \-top 2702 .RS 4 2703 各出力ファイルの最上部に配置するテキストを指定します。 2704 .RE 2705 .PP 2706 \-bottom \fItext\fR 2707 .RS 4 2708 各出力ファイルの最下部に配置するテキストを指定します。このテキストは、下部ナビゲーション・バーより下の、ページの最下部に配置されます。テキストにはHTMLタグおよび空白文字を含めることができますが、その場合、テキストを引用符で囲む必要があります。テキスト内部の引用符にはエスケープ文字を使用します。 2709 .RE 2710 .PP 2711 \-link \fIextdocURL\fR 2712 .RS 4 2713 既存のJavadocにより生成された外部参照クラスのドキュメントへのリンクを作成します。\fIextdocURL\fR引数は、リンク先として指定する、Javadocにより生成された外部ドキュメントを含むディレクトリの絶対URLまたは相対URLです。指定した\fIjavadoc\fRコマンドの実行で、複数の\fI\-link\fRオプションを指定して複数のドキュメントへのリンクを作成できます。 2714 .sp 2715 このディレクトリ内にpackage\-listファイルが存在する必要があります(存在しない場合は、\fI\-linkoffline\fRオプションを使用します)。\fIjavadoc\fRコマンドは、package\-listファイルからパッケージ名を読み取った後、そのURLでこれらのパッケージにリンクします。\fIjavadoc\fRコマンドの実行時に、\fIextdocURL\fRの値が、作成された\fI<A HREF>\fRリンク内にコピーされます。したがって、\fIextdocURL\fRはファイルではなくディレクトリへのURLである必要があります。\fIextdocURL\fRに絶対リンクを使用すると、ユーザーのドキュメントを任意のWebサイト上のドキュメントにリンクできます。相対位置へリンクするのみの場合は相対リンクを使用できます。相対リンクを使用する場合、渡す値は宛先ディレクトリから、リンクされているパッケージを含むディレクトリへである必要があります(\fI\-d\fRオプションで指定)。絶対リンクを指定する場合、通常、HTTPリンクを使用します。ただし、Webサーバーを持たないファイル・システムにリンクする場合は、ファイル・リンクを使用できます。生成されたドキュメンテーションにアクセスする全員が同じファイル・システムを共有する場合にのみファイル・リンクを使用します。どの場合も、どのオペレーティング・システムでも、URLが絶対または相対のいずれでも、また\fIh\fR\fIttp:\fRまたは\fIf\fR\fIile:\fRのいずれでも、URLメモ: Uniform Resource Locators 2716 (http://www\&.ietf\&.org/rfc/rfc1738\&.txt)に指定されているとおり、区切り文字としてスラッシュを使用します。 2717 .sp 2718 .if n \{\ 2719 .RS 4 2720 .\} 2721 .nf 2722 \-link http://<host>/<directory>/<directory>/\&.\&.\&./<name> 2723 \-link file://<host>/<directory>/<directory>/\&.\&.\&./<name> 2724 \-link <directory>/<directory>/\&.\&.\&./<name> 2725 .fi 2726 .if n \{\ 2727 .RE 2728 .\} 2729 .RE 2730 \-linkofflineおよび\-linkオプションの違い.PP 2731 次の場合に、\fI\-link\fRオプションを使用します。 2732 .sp 2733 .RS 4 2734 .ie n \{\ 2735 \h'-04'\(bu\h'+03'\c 2736 .\} 2737 .el \{\ 2738 .sp -1 2739 .IP \(bu 2.3 2740 .\} 2741 外部APIドキュメントへの相対パスを使用する場合。 2742 .RE 2743 .sp 2744 .RS 4 2745 .ie n \{\ 2746 \h'-04'\(bu\h'+03'\c 2747 .\} 2748 .el \{\ 2749 .sp -1 2750 .IP \(bu 2.3 2751 .\} 2752 外部APIドキュメントへの絶対URLを使用する場合(そのURLに接続し、読取りを行うことがシェルによって許可されている場合)。 2753 .RE 2754 .PP 2755 外部APIドキュメントへの絶対URLを使用する場合(そのURLに接続し、読取りを行うことがシェルによって許可されていない場合)は\fI\-linkoffline\fRオプションを使用します。このような状況は、ファイアウォールの内側からファイアウォールの外側にあるドキュメントにリンクしようとする場合に発生します。 2756 .PP 2757 \fBExample 1\fR, 外部ドキュメントへの絶対リンク 2758 .RS 4 2759 http://docs\&.oracle\&.com/javase/8/docs/api/index\&.htmlに示すような、\fIjava\&.lang\fR、\fIjava\&.io\fRおよびその他のJavaプラットフォーム・パッケージにリンクする場合、次のコマンドを使用します 2760 .sp 2761 .if n \{\ 2762 .RS 4 2763 .\} 2764 .nf 2765 javadoc \-link http://docs\&.oracle\&.com/javase/8/docs/api/ com\&.mypackage 2766 .fi 2767 .if n \{\ 2768 .RE 2769 .\} 2770 このコマンドは、Java SEプラットフォーム・パッケージへのリンク持つ\fIcom\&.mypackage\fRパッケージのドキュメントを生成します。生成ドキュメントには、たとえばクラス\fItrees\fR内の\fIObject\fRクラスへのリンクが含まれています。\fI\-sourcepath\fRや\fI\-d\fRなどの他のオプションは表示されません。 2771 .RE 2772 .PP 2773 \fBExample 2\fR, 外部ドキュメントへの相対リンク 2774 .RS 4 2775 この例では、2つのパッケージがあり、そのドキュメントは\fIjavadoc\fRコマンドを複数回実行した結果生成されたものです。さらに、これらのドキュメントは相対パスで分割されています。パッケージは、APIである\fIcom\&.apipackage\fRと、SPI(サービス・プロバイダ・インタフェース)であるc\fIom\&.spipackage\fRです。ドキュメントの格納先は、docs/api/com/apipackageとdocs/spi/com/spipackageです。APIパッケージのドキュメントはすでに生成されていて、docsが現在のディレクトリである場合、APIドキュメントへのリンクを持つSPIパッケージをドキュメント化するには、次のコマンドを実行します。\fIjavadoc \-d \&./spi \-link \&.\&./api com\&.spipackage\fR 2776 .sp 2777 \fI\-link\fRオプションは、宛先ディレクトリ(docs/spi)からの相対パスです。 2778 .RE 2779 注意.PP 2780 \fI\-link\fRオプションを使用すると、コードからは参照されていても、今回の\fIjavadoc\fRの実行ではドキュメント化されないクラスにリンクできるようになります。リンクから有効なページに移動できるようにするには、それらのHTMLページがある場所を調べ、その場所を\fIextdocURL\fRに指定する必要があります。これにより、サードパーティのドキュメンテーションがjava\&.*ドキュメンテーション(http://docs\&.oracle\&.com)へリンクすることができます。\fIjavadoc\fRコマンドで、現在の実行で生成しているドキュメンテーション内のAPIへのリンクのみを作成する場合には、\fI\-link\fRオプションを省略します。\fI\-link\fRオプションを指定しないと、\fIjavadoc\fRコマンドは外部参照のためのドキュメンテーションへのリンクを作成しません。ドキュメンテーションが存在するのかどうか、またはどこに存在するのかがわからないからです。\fI\-link\fRオプションでは、生成ドキュメンテーション内の複数の場所にリンクを作成できます。ソース・ファイルの処理を参照してください。もう1つの用途は、パッケージ・セットの間にクロスリンクを作成することです。一方のパッケージ・セットに対して\fIjavadoc\fRコマンドを実行した後、他方のパッケージ・セットに対して\fIjavadoc\fRコマンドを再度実行すると、両セット間に双方向のリンクを作成できます。 2781 クラスの参照方法.PP 2782 表示される外部参照クラスへのリンクの場合(およびそのテキスト・ラベルだけではなく)、クラスは次の方法で参照される必要があります。メソッドの本体でクラスを参照するのみでは十分ではありません。\fIimport\fR文、宣言のいずれかで参照する必要があります。次に、クラス\fIjava\&.io\&.File\fRを参照する方法の例を示します。 2783 .PP 2784 すべてのタイプのimport文の場合。ワイルドカードによるインポート、名前による明示的なインポート、または\fIjava\&.lang\&.*\fRに対する自動インポート。 2785 .PP 2786 Java SE 1\&.3\&.\fIn\fRおよび1\&.2\&.\fIn\fRでは、名前による明示的なインポートのみ機能します。ワイルドカードによる\fIimport\fR文も、\fIimport java\&.lang\&.*\fRの自動インポートも機能しません。 2787 .PP 2788 宣言の場合: 2789 \fIvoid mymethod(File f) {}\fR 2790 .PP 2791 参照は、メソッド、コンストラクタ、フィールド、クラスまたはインタフェースの戻り型またはパラメータ・タイプ、あるいは実装、拡張またはスロー文にあります。 2792 .PP 2793 重要な結果として、\fI\-link\fRオプションを使用しても、この制限のために誤って表示されないリンクが多数発生する可能性があります。テキストはハイパーテキスト・リンクが付けられずに表示されます。リンクが表示する警告から、これらのリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するための最も簡単な方法はそのクラスをインポートすることです。 2794 パッケージ・リスト.PP 2795 \fI\-link\fRオプションには、\fIjavadoc\fRコマンドによって生成されるpackage\-listという名前のファイルが、\fI\-link\fRオプションに指定したURLに存在していることが必要です。package\-listファイルは、その場所にあるドキュメント化されたパッケージの名前のリストが入った単純なテキスト・ファイルです。前述の例では、\fIjavadoc\fRコマンドは、指定したURLでpackage\-listという名前のファイルを検索し、パッケージ名を読み取って、そのURLでこれらのパッケージにリンクします。 2796 .PP 2797 たとえば、Java SE APIのパッケージ・リストは 2798 http://docs\&.oracle\&.com/javase/8/docs/api/package\-listにあります。 2799 .PP 2800 このパッケージ・リストは次のような内容で始まっています。 2801 .sp 2802 .if n \{\ 2803 .RS 4 2804 .\} 2805 .nf 2806 java\&.applet 2807 java\&.awt 2808 java\&.awt\&.color 2809 java\&.awt\&.datatransfer 2810 java\&.awt\&.dnd 2811 java\&.awt\&.event 2812 java\&.awt\&.font 2813 and so on \&.\&.\&.\&. 2814 .fi 2815 .if n \{\ 2816 .RE 2817 .\} 2818 .PP 2819 \fI\-link\fRオプションを指定せずに\fIjavadoc\fRを実行した場合、外部参照クラスに属する名前を見つけると、その名前をリンクなしで出力します。一方、\fI\-link\fRオプションを指定した場合、\fIjavadoc\fRコマンドは、指定された\fIextdocURL\fRの場所にあるpackage\-listファイルでそのパッケージ名を検索します。パッケージ名が見つかると、\fIextdocURL\fRが名前の前に付加されます。 2820 .PP 2821 すべてのリンクが正しく機能するためには、外部参照のすべてのドキュメントが、指定したURLに存在する必要があります。\fIjavadoc\fRコマンドは、指定されたpackage\-listが存在するかどうかのみをチェックし、これらのページが存在するかどうかはチェックしません。 2822 複数のリンク.PP 2823 複数の\fI\-link\fRオプションを指定すると、任意の数の外部生成ドキュメントへのリンクを作成できます。Javadoc 1\&.2には、複数の\fI\-link\fRオプションを指定できないという既知の不具合があります。これはJavadoc 1\&.2\&.2で修正されました。リンクする外部ドキュメントごとに、次のように別々のリンク・オプションを指定します。\fIjavadoc \-link extdocURL1 \-link extdocURL2 \&.\&.\&. \-link extdocURLn com\&.mypackage\fR 2824 \fIextdocURL1\fR、\fIextdocURL2\fR、\&.\fI\&.\&. extdocURLn\fRは、それぞれ外部ドキュメントのルートを指し、各ルートには、package\-listという名前のファイルが入っています。 2825 クロスリンク.PP 2826 以前に作成された複数のドキュメントをクロスリンクする場合、ブートストラップが必要になることがあります。どのドキュメントについてもpackage\-listが存在していない場合は、最初のドキュメントに対して\fIjavadoc\fRコマンドを実行する時点で、2番目のドキュメントのpackage\-listはまだ存在していません。したがって、外部リンクを作成するには、2番目のドキュメントを生成した後で、最初のドキュメントを生成しなおす必要があります。 2827 .PP 2828 この場合、最初のドキュメント生成の目的は、package\-listを作成することです(パッケージ名を把握している場合は手動で作成してもかまいません)。次に、2番目のドキュメントとその外部リンクを生成します。必要な外部のpackage\-listファイルが存在しない場合は、\fIjavadoc\fRコマンドから警告が出力されます。 2829 .PP 2830 \-linkoffline \fIextdocURL packagelistLoc\fR 2831 .RS 4 2832 このオプションは\fI\-link\fRオプションのバリエーションです。両方とも、Javadocにより生成された外部参照クラスのドキュメントへのリンクを作成します。\fIjavadoc\fRコマンドがWeb接続を使用してドキュメントにアクセスできないとき、Web上のドキュメントにリンクするには、\fI\-link\fRo\fIffline\fRオプションを使用します。外部ドキュメントのpackage\-listファイルにアクセスできないとき、またはこのファイルが\fIextdocURL\fRで指定された場所には存在せず、\fIpackageListLoc\fRで指定できる別の場所(通常ローカル)に存在するとき、\fI\-linkoffline\fRオプションを使用します。\fIextdocURL\fRにWorld Wide Web上でしかアクセスできない場合は、\fI\-linkoffline\fRオプションを指定することにより、ドキュメントの生成時に\fIjavadoc\fRコマンドがWebに接続する必要があるという制約がなくなります。もう1つの用途は、ドキュメントを更新するための回避策として使用することです。パッケージのセット全体に対して\fIjavadoc\fRコマンドを実行した後、変更した一部のパッケージに対してのみ\fIjavadoc\fRコマンドを再度実行して、更新されたファイルを、オリジナルのセットに挿入できるようにします。次に例を示します。\fI\-linkoffline\fRオプションは引数を2つ取ります。第1引数は\fI<a href>\fRリンクに組み込まれる文字列を指定し、第2引数はpackage\-listの検索場所を\fI\-linkoffline\fRに伝えます。 2833 .sp 2834 .RS 4 2835 .ie n \{\ 2836 \h'-04'\(bu\h'+03'\c 2837 .\} 2838 .el \{\ 2839 .sp -1 2840 .IP \(bu 2.3 2841 .\} 2842 \fIextdocURL\fRの値は、リンク先として指定する、Javadocにより生成された外部ドキュメントを含むディレクトリの絶対URLまたは相対URLです。相対URLの場合、値は、生成先ディレクトリ(\fI\-d\fRオプションで指定)からリンク先となるパッケージのルートへの相対パスにする必要があります。詳細は、\fI\-link\fRオプションの\fIextdocURL\fRを参照してください。 2843 .RE 2844 .sp 2845 .RS 4 2846 .ie n \{\ 2847 \h'-04'\(bu\h'+03'\c 2848 .\} 2849 .el \{\ 2850 .sp -1 2851 .IP \(bu 2.3 2852 .\} 2853 \fIpackagelistLoc\fRの値は、外部ドキュメントのpackage\-listファイルを含むディレクトリへのパスまたはURLです。これは、URL (http:またはfile:)でもファイル・パスでもかまいません。また、絶対パスと相対パスのどちらでもかまいません。相対パスの場合は、\fIjavadoc\fRコマンドが実行される現在のディレクトリからの相対パスとして指定します。package\-listファイル名を含めないでください。 2854 .sp 2855 指定した\fIjavadoc\fRコマンドの実行で、複数の\fI\-link\fRオプションを指定できます。Javadoc 1\&.2\&.2より前では、\fI\-linkfile\fRオプションは1回しか指定できませんでした。 2856 .RE 2857 .RE 2858 外部ドキュメントへの絶対リンク.PP 2859 http://docs\&.oracle\&.com/javase/8/docs/api/index\&.htmlに示すような、\fIjava\&.lang\fR、 2860 \fIjava\&.io\fRおよびその他のJava SEパッケージにリンクする必要がある場合があります。 2861 .PP 2862 ただし、シェルにはWebアクセス権がありません。この場合、次を行います。 2863 .sp 2864 .RS 4 2865 .ie n \{\ 2866 \h'-04' 1.\h'+01'\c 2867 .\} 2868 .el \{\ 2869 .sp -1 2870 .IP " 1." 4.2 2871 .\} 2872 ブラウザでpackage\-listファイルを開きます(http://docs\&.oracle\&.com/javase/8/docs/api/package\-list) 2873 .RE 2874 .sp 2875 .RS 4 2876 .ie n \{\ 2877 \h'-04' 2.\h'+01'\c 2878 .\} 2879 .el \{\ 2880 .sp -1 2881 .IP " 2." 4.2 2882 .\} 2883 ファイルをローカル・ディレクトリに保存し、このローカル・コピーを第2引数\fIpackagelistLoc\fRで指定します。この例では、パッケージ・リスト・ファイルはカレント・ディレクトリ(\&.)に保存されています。 2884 .RE 2885 .PP 2886 次のコマンドは、Java SEプラットフォーム・パッケージへのリンクを持つc\fIom\&.mypackage\fRパッケージのドキュメントを生成します。生成ドキュメントには、たとえばクラス\fItrees\fR内の\fIObject\fRクラスへのリンクが含まれています。\fI\-sourcepath\fRなど、他の必要なオプションは表示されません。 2887 .sp 2888 .if n \{\ 2889 .RS 4 2890 .\} 2891 .nf 2892 javadoc \-linkoffline http://docs\&.oracle\&.com/javase/8/docs/api/ \&. com\&.mypackage 2893 .fi 2894 .if n \{\ 2895 .RE 2896 .\} 2897 外部ドキュメントへの相対リンク.PP 2898 \fI\-linkoffline\fRを相対パスとともに使用することはあまりありません。理由は単純で、通常は\fI\-link\fRで間に合うからです。\fI\-linkoffline\fRオプションを使用する場合、通常、package\-listファイルはローカルで、相対リンクを使用する場合はリンク先のファイルもローカルなので、通常は\fI\-linkoffline\fRオプションの2つの引数に、異なるパスを指定する必要はありません。2つの引数が同一の場合、\fI\-link\fRオプションを使用できます。 2899 package\-listファイルの手動での作成.PP 2900 package\-listファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルのコピーを手動で作成し、\fIpackagelistLoc\fRでそのパスを指定することができます。\fIcom\&.apipackage\fRが最初に生成された時点で\fIcom\&.spipackage\fRのパッケージ・リストが存在しないという前出のケースが一例として挙げられます。この方法は、パッケージ名はわかっているものの、まだ公開されていない、新しい外部ドキュメントにリンクするドキュメントを生成する必要がある場合に便利です。また、package\-listファイルが生成されないJavadoc 1\&.0または1\&.1で生成されたパッケージ用にpackage\-listファイルを作成する場合にも、この方法が使用できます。同様に、2つの企業が未公開のpackage\-listファイルを共有できるため、クロスリンクを設定したドキュメントを同時にリリースすることも可能になります。 2901 複数ドキュメントへのリンク.PP 2902 参照先の生成ドキュメントごとに1回、\fI\-linkoffline\fRオプションを含めることができます。 2903 .sp 2904 .if n \{\ 2905 .RS 4 2906 .\} 2907 .nf 2908 javadoc \-linkoffline extdocURL1 packagelistLoc1 \-linkoffline extdocURL2 2909 packagelistLoc2 \&.\&.\&. 2910 .fi 2911 .if n \{\ 2912 .RE 2913 .\} 2914 ドキュメントの更新.PP 2915 プロジェクトに何十または何百のパッケージが含まれる場合にも、\fI\-linkoffline\fRオプションを使用できます。ソース・ツリー全体ですでに\fIjavadoc\fRコマンドを実行したことがある場合、ドキュメンテーション・コメントにわずかな変更を迅速に加え、ソース・ツリーの一部で\fIjavadoc\fRコマンドを再実行することができます。2回目の実行は、ドキュメンテーション・コメントを変更し、宣言は変更しない場合にのみ正しく処理されることに注意してください。ソース・コードに対して宣言を追加、削除、または変更した場合は、索引、パッケージ・ツリー、継承されるメンバーのリスト、使用ページなどの場所で、リンクが壊れることがあります。 2916 .PP 2917 まず、この新しい小規模な実行で使用する、新しい生成先ディレクトリ(updateなど)を作成します。この例では、元の生成先ディレクトリの名前はhtmlです。最も単純な例では、htmlディレクトリの親ディレクトリに移動します。\fI\-linkoffline\fRオプションの第1引数にカレント・ディレクトリ(\&.)を設定し、第2引数にpackage\-listが検索されるhtmlへの相対パスを設定し、更新するパッケージのパッケージ名のみを渡します。 2918 .sp 2919 .if n \{\ 2920 .RS 4 2921 .\} 2922 .nf 2923 javadoc \-d update \-linkoffline \&. html com\&.mypackage 2924 .fi 2925 .if n \{\ 2926 .RE 2927 .\} 2928 .PP 2929 \fIjavadoc\fRコマンドの終了後、update/com/package内の生成されたクラスのページをコピーし(概要や索引は除く)、html/com/package内の元のファイルに上書きします。 2930 .PP 2931 \-linksource 2932 .RS 4 2933 各ソース・ファイル(行番号付き)のHTMLバージョンを作成し、標準HTMLドキュメントからソース・ファイルへのリンクを追加します。リンクは、ソース・ファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。そうでない場合、たとえばデフォルト・コンストラクタや生成されたクラスに対しては、リンクは作成されません。 2934 .sp 2935 このオプションは、\fI\-public\fR、\fI\-package\fR、\fI\-protected\fRおよび\fI\-private\fRの各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソース・ファイル内のすべての非公開実装の詳細を公開します。\fI\-private\fRオプションもあわせて指定しないかぎり、非公開のクラスやインタフェースの一部には、リンクを介してアクセスできないことがあります。 2936 .sp 2937 各リンクは、その宣言内の識別子名の上に作成されます。たとえば、\fIButton\fRクラスのソース・コードへのリンクは、\fIButton\fRという語の上に作成されます。 2938 .sp 2939 .if n \{\ 2940 .RS 4 2941 .\} 2942 .nf 2943 public class Button extends Component implements Accessible 2944 .fi 2945 .if n \{\ 2946 .RE 2947 .\} 2948 \fIButton\fRクラスの\fIgetLabel\fRメソッドのソース・コードへのリンクは、\fIgetLabel\fRという語の上に作成されます。 2949 .sp 2950 .if n \{\ 2951 .RS 4 2952 .\} 2953 .nf 2954 public String getLabel() 2955 .fi 2956 .if n \{\ 2957 .RE 2958 .\} 2959 .RE 2960 .PP 2961 \-group groupheading \fIpackagepattern:packagepattern\fR 2962 .RS 4 2963 概要ページの複数のパッケージを、指定したグループに分けて、グループごとに表を作成します。各グループは、それぞれ別の\fI\-group\fRオプションで指定します。グループは、コマンド行で指定された順序でページに表示されます。パッケージは、グループ内でアルファベット順になっています。指定した\fI\-group\fRオプションでは、\fIpackagepattern\fR式のリストに一致するパッケージが、見出しとして\fIgroupheading\fRを持つ1つの表に表示されます。 2964 .sp 2965 .RS 4 2966 .ie n \{\ 2967 \h'-04'\(bu\h'+03'\c 2968 .\} 2969 .el \{\ 2970 .sp -1 2971 .IP \(bu 2.3 2972 .\} 2973 \fIgroupheading\fRには、任意のテキストを指定でき、空白を含めることができます。指定したテキストは、グループの表見出しになります。 2974 .RE 2975 .sp 2976 .RS 4 2977 .ie n \{\ 2978 \h'-04'\(bu\h'+03'\c 2979 .\} 2980 .el \{\ 2981 .sp -1 2982 .IP \(bu 2.3 2983 .\} 2984 \fIpackagepattern\fRの値には、任意のパッケージ名の先頭部分とそれに続く1つのアスタリスク(*)で任意のパッケージ名を指定できます。アスタリスクは使用できる唯一のワイルドカードで、任意の文字に一致する、という意味です。1つのグループには、コロン(:)で区切って複数のパターンを含めることができます。パターンまたはパターン・リストでアスタリスクを使用する場合、パターン・リストは\fI"java\&.lang*:java\&.util"\fRのように引用符で囲む必要があります。 2985 .RE 2986 .sp 2987 \fI\-group\fRオプションを指定しない場合は、見出し\fIPackages\fRおよび適切な小見出しを持つ1つのグループに配置されます。小見出しにすべてのドキュメント化されるパッケージ(すべてのグループ)が含まれるわけではない場合、残りのパッケージは「その他のパッケージ」というサブ見出しを持つ独立したグループに入れられます。 2988 .sp 2989 たとえば、次の\fIjavadoc\fRコマンドでは、3つのドキュメント化されたパッケージが\fI「コア」\fR、\fI「拡張」\fRおよび\fI「その他のパッケージ」\fRに分けられます。\fIjava\&.lang*\fRでは、最後のドット(\&.)を指定していません。\fIjava\&.lang\&.*\fRのようにドットを入れると、\fI java\&.lang\fRパッケージは除外されることになります。 2990 .sp 2991 .if n \{\ 2992 .RS 4 2993 .\} 2994 .nf 2995 javadoc \-group "Core Packages" "java\&.lang*:java\&.util" 2996 \-group "Extension Packages" "javax\&.*" 2997 java\&.lang java\&.lang\&.reflect java\&.util javax\&.servlet java\&.new 2998 .fi 2999 .if n \{\ 3000 .RE 3001 .\} 3002 \fBコア・パッケージ\fR 3003 .sp 3004 \fIjava\&.lang\fR 3005 .sp 3006 \fIjava\&.lang\&.reflect\fR 3007 .sp 3008 \fIjava\&.util\fR 3009 .sp 3010 \fB拡張機能パッケージ\fR 3011 .sp 3012 \fIjavax\&.servlet\fR 3013 .sp 3014 \fBOther Packages\fR 3015 .sp 3016 \fIjava\&.new\fR 3017 .RE 3018 .PP 3019 \-nodeprecated 3020 .RS 4 3021 非推奨のAPIをドキュメントに生成しないようにします。このオプションを指定すると、\fI\-nodeprecatedlist\fRオプションを指定した場合と同じ効果があり、ドキュメントの他の部分全体でも、非推奨のAPIが生成されません。このオプションは、コードを記述しているとき、非推奨のコードによって気を散らされたくない場合に便利です。 3022 .RE 3023 .PP 3024 \-nodeprecatedlist 3025 .RS 4 3026 非推奨のAPIのリストを含むファイル(deprecated\-list\&.html)、およびナビゲーション・バーのそのページへのリンクが生成されないようにします。\fIjavadoc\fRコマンドでは、引き続き、ドキュメントの他の部分では、非推奨のAPIが生成されます。このオプションは、非推奨のAPIがソース・コードに含まれておらず、ナビゲーション・バーをすっきりと見せる場合に便利です。 3027 .RE 3028 .PP 3029 \-nosince 3030 .RS 4 3031 生成ドキュメントから、\fI@since\fRタグに関連付けられた\fI「導入されたバージョン」\fRセクションを省略します。 3032 .RE 3033 .PP 3034 \-notree 3035 .RS 4 3036 生成ドキュメントから、クラスおよびインタフェースの階層ページを省略します。これらのページには、ナビゲーション・バーの「階層ツリー」ボタンからアクセスできます。デフォルトでは、階層が生成されます。 3037 .RE 3038 .PP 3039 \-noindex 3040 .RS 4 3041 生成ドキュメントから、索引を省略します。デフォルトでは、索引が生成されます。 3042 .RE 3043 .PP 3044 \-nohelp 3045 .RS 4 3046 出力の各ページの最上部と最下部にあるナビゲーション・バーから「ヘルプ」リンクを省略します。 3047 .RE 3048 .PP 3049 \-nonavbar 3050 .RS 4 3051 通常、生成されるページの最上部と最下部に表示されるナビゲーション・バー、ヘッダー、およびフッターを生成しないようにします。\fI\-nonavbar\fRオプションは\fI\-bottom\fRオプションに影響を与えません。\fI\-nonavbar\fRオプションは、印刷するためにのみファイルをPostScriptやPDFに変換する場合など、内容のみが重要で、ナビゲーションの必要がない場合に便利です。 3052 .RE 3053 .PP 3054 \-helpfile \fIpath\efilename\fR 3055 .RS 4 3056 最上部および最下部のナビゲーション・バーの「ヘルプ」リンクのリンク先となる代替ヘルプ・ファイルpath\efilenameのパスを指定します。このオプションが指定されていないと、\fIjavadoc\fRコマンドは、\fIjavadoc\fRコマンド内でハードコードされているヘルプ・ファイルhelp\-doc\&.htmlを自動作成します。このオプションを使用すると、デフォルトをオーバーライドできます。ファイル名にはどんな名前でも指定でき、help\-doc\&.htmlに限定されません。\fIjavadoc\fRコマンドは、次の例のように、ナビゲーション・バー内のリンクを必要に応じて調整します。 3057 .sp 3058 .if n \{\ 3059 .RS 4 3060 .\} 3061 .nf 3062 javadoc \-helpfile /home/user/myhelp\&.html java\&.awt\&. 3063 .fi 3064 .if n \{\ 3065 .RE 3066 .\} 3067 .RE 3068 .PP 3069 \-stylesheet \fIpath/filename \fR 3070 .RS 4 3071 代替HTMLスタイルシート・ファイルのパスを指定します。このオプションが指定されていないと、\fIjavadoc\fRコマンドは、\fIjavadoc\fRコマンド内でハードコードされているスタイルシート・ファイルstylesheet\&.cssを自動作成します。このオプションを使用すると、デフォルトをオーバーライドできます。ファイル名にはどんな名前でも指定でき、stylesheet\&.cssに限定されません。 3072 .sp 3073 .if n \{\ 3074 .RS 4 3075 .\} 3076 .nf 3077 javadoc \-stylesheet file /home/user/mystylesheet\&.css com\&.mypackage 3078 .fi 3079 .if n \{\ 3080 .RE 3081 .\} 3082 .RE 3083 .PP 3084 \-serialwarn 3085 .RS 4 3086 \fI@serial\fRタグがない場合は、コンパイル時に警告を生成します。デフォルトでは、Javadoc 1\&.2\&.2以降では、直列化の警告は生成されません。以前のリリースとは逆の動作です。このオプションを使用すると、直列化の警告が表示されるので、デフォルトの直列化可能フィールドと\fIwriteExternal\fRメソッドを適切にドキュメント化するのに役立ちます。 3087 .RE 3088 .PP 3089 \-charset \fIname\fR 3090 .RS 4 3091 このドキュメント用のHTML文字セットを指定します。この名前は、IANA RegistryのCharacter Sets 3092 (http://www\&.iana\&.org/assignments/character\-sets)に示された、優先MIME名である必要があります。 3093 .sp 3094 たとえば、\fIjavadoc \-charset "iso\-8859\-1" mypackage\fRは次の行を生成された各ページのヘッダーに挿入します。 3095 .sp 3096 .if n \{\ 3097 .RS 4 3098 .\} 3099 .nf 3100 <META http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1"> 3101 .fi 3102 .if n \{\ 3103 .RE 3104 .\} 3105 この\fIMETA\fRタグは、HTML標準(4197265および4137321)のHTML Document Representation 3106 (http://www\&.w3\&.org/TR/REC\-html40/charset\&.html#h\-5\&.2\&.2)に記載されています。 3107 .sp 3108 およびオプションも参照してください。 3109 .RE 3110 .PP 3111 \-docencoding \fIname\fR 3112 .RS 4 3113 生成されるHTMLファイルのエンコーディングを指定します。この名前は、IANA RegistryのCharacter Sets 3114 (http://www\&.iana\&.org/assignments/character\-sets)に示された、優先MIME名である必要があります。 3115 .sp 3116 \fI\-docencoding\fRオプションを省略し、\fI\-encoding\fRオプションを使用すると、生成されたHTMLファイルの暗号化は\fI\-encoding\fRオプションで特定されます。例: 3117 \fIjavadoc \-docencoding"iso\-8859\-1" mypackage\fRおよびオプションも参照してください。 3118 .RE 3119 .PP 3120 \-keywords 3121 .RS 4 3122 HTMLキーワード<META>タグを、クラスごとに生成されるファイルに追加します。これらのタグは、<META>タグを検索するサーチ・エンジンがページを見つける場合に役立ちます。インターネット全体を検索する検索エンジンのほとんどは<META>タグを参照しません。ページが誤用している可能性があるからです。自身のWebサイトへの検索を制限する、企業により提供される検索エンジンは、<META>タグを参照することで恩恵を受けることができます。<META>タグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス\fIString\fRは次のキーワードで開始します。 3123 .sp 3124 .if n \{\ 3125 .RS 4 3126 .\} 3127 .nf 3128 <META NAME="keywords" CONTENT="java\&.lang\&.String class"> 3129 <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER"> 3130 <META NAME="keywords" CONTENT="length()"> 3131 <META NAME="keywords" CONTENT="charAt()"> 3132 .fi 3133 .if n \{\ 3134 .RE 3135 .\} 3136 .RE 3137 .PP 3138 \-tag \fItagname\fR:Xaoptcmf:"\fItaghead\fR" 3139 .RS 4 3140 \fIjavadoc\fRコマンドがドキュメンテーション・コメント内の引数を1つ取る単純なカスタム・ブロック・タグ\fI@tagname\fRを解釈できるようにします。これにより、\fIjavadoc\fRコマンドはタグ名のスペルチェックを行うことができるので、ソース・コード内に存在するすべてのカスタム・タグについて、\fI\-tag\fRオプションを組み込むことが重要です。今回の実行では出力されないタグは、\fIX\fRを付けて無効にします。\fI\-tag\fRオプションは、タグの見出し\fItaghead\fRを太字で出力します。その次の行には、このオプションの1つの引数で指定したテキストが続きます。ブロック・タグと同様、この引数のテキストにはインライン・タグを含めることができます。このインライン・タグも解釈されます。出力は、引数を1つ取る標準のタグ(\fI@return\fRや\fI@author\fRなど)の出力とよく似ています。\fItaghead\fRの値を省略すると、\fItagname\fRが見出しとして表示されます。 3141 .sp 3142 \fBタグの配置\fR: 3143 \fIXaoptcmf\fR引数により、ソース・コード内でタグを配置できる場所が決まり、タグを無効にできるかどうか(\fIX\fRを使用して)が決まります。タグの配置位置を制限しない場合は\fIa\fRを指定します。それ以外の文字の組合せも可能です。 3144 .sp 3145 \fIX\fR 3146 (タグの無効化) 3147 .sp 3148 \fIa\fR 3149 (すべて) 3150 .sp 3151 \fIo\fR 3152 (概要) 3153 .sp 3154 \fIp\fR 3155 (パッケージ) 3156 .sp 3157 \fIt\fR 3158 (タイプ、つまりクラスとインタフェース) 3159 .sp 3160 \fIc\fR 3161 (コンストラクタ) 3162 .sp 3163 \fIm\fR 3164 (メソッド) 3165 .sp 3166 \fIf\fR 3167 (フィールド) 3168 .sp 3169 \fBシングル・タグの例\fR: ソース・コード内の任意の位置で使用できるタグのタグ・オプションの例を示します。\fI\-tag todo:a:"To Do:"\fR 3170 .sp 3171 \fI@todo\fRタグをコンストラクタ、メソッドおよびフィールドとのみ使用する場合、\fI\-tag todo:cmf:"To Do:"\fRを使用します。 3172 .sp 3173 最後のコロン(:)は、パラメータ区切り文字ではなく、見出しテキストの一部になっています。\fI@todo\fRタグを含む、ソース・コード用のいずれかのタグ・オプションを使用します。たとえば、\fI@todo The documentation for this method needs work\fRです。 3174 .sp 3175 \fBタグ名内のコロン\fR: タグ名内でコロンを使用する場合はバックスラッシュを使用してエスケープします。次のドキュメンテーション・コメントには、\fI\-tag ejb\e\e:bean:a:"EJB Bean:"\fRオプションを使用します。 3176 .sp 3177 .if n \{\ 3178 .RS 4 3179 .\} 3180 .nf 3181 /** 3182 * @ejb:bean 3183 */ 3184 .fi 3185 .if n \{\ 3186 .RE 3187 .\} 3188 \fBタグ名のスペルチェック\fR: 一部の開発者が必ずしも出力しないカスタム・タグをソース・コード内に配置することがあります。この場合、ソース・コード内のすべてのタグをリストし、出力するタグを有効にし、出力しないタグを無効にする必要があります。\fIX\fRを指定するとタグは無効になります。指定しないと、タグは有効になります。これにより、\fIjavadoc\fRコマンドは、検出したタグが入力ミスなどによる不明タグであるかどうかを特定できます。このような場合に、\fIjavadoc\fRコマンドから警告が出力されます。すでに配置されている値に\fIX\fRを追加できます。こうしておけば、\fIX\fRを削除するのみでタグを有効にすることができます。たとえば、\fI@todo\fRタグを出力で抑制する場合、\fI\-tag todo:Xcmf:"To Do:"\fRを使用します。さらに簡単にする場合、\fI\-tag todo:X\fRを使用します。構文\fI\-tag todo:X\fRは、\fI@todo\fRタグがタグレットで定義されていても機能します。 3189 .sp 3190 \fBタグの順序\fR: 3191 \fI\-ta\fR\fIg\fRおよび\fI\-taglet\fRオプションの順序によって、タグの出力順が決まります。カスタム・タグと標準タグを組み合せて使用することもできます。標準タグのタグ・オプションは、順序を決定するためだけのプレースホルダです。標準タグの名前のみを取ります。標準タグの小見出しは変更できません。これを次の例に示します。\fI\-tag\fRオプションを指定しないと、\fI\-tagle\fR\fIt\fRオプションの位置により、順序が決まります。タグが両方とも存在する場合、コマンドラインの最後にある方がその順序を決定します。これは、タグやタグレットがコマンドラインに指定された順番に処理されるためです。たとえば、\fI\-taglet\fRおよび\fI\-tag\fRオプションが名前\fItodo\fR値を持つ場合、コマンドラインに最後に指定されたものが順序を決定します。 3192 .sp 3193 \fBタグの完全セットの例\fR: この例では、出力のParametersとThrowsの間にTo Doを挿入します。\fIX\fRを使用して、\fI@example\fRタグが、ソース・コード内の今回の実行では出力されないタグであることも指定します。\fI@argfile\fRタグを使用する場合は、次のように、引数ファイル内の別々の行にタグを配置できます(行の継続を示す文字は不要)。 3194 .sp 3195 .if n \{\ 3196 .RS 4 3197 .\} 3198 .nf 3199 \-tag param 3200 \-tag return 3201 \-tag todo:a:"To Do:" 3202 \-tag throws 3203 \-tag see 3204 \-tag example:X 3205 .fi 3206 .if n \{\ 3207 .RE 3208 .\} 3209 \fIjavadoc\fRコマンドがドキュメンテーション・コメントを解析する際に検索されたタグのうち、標準タグでも、\fI\-tag\fRや\fI\-taglet\fRオプションで渡されたタグでもないものはすべて不明タグとみなされ、警告がスローされます。 3210 .sp 3211 標準タグは、最初、デフォルトの順序でリスト内に内部的に格納されます。\fI\-tag\fRオプションを使用すると、それらのタグはこのリストに追加されます。標準タグは、デフォルトの位置から移動されます。そのため、標準タグの\fI\-tag\fRオプションを省略すると、それはデフォルトの位置に配置されたままになります。 3212 .sp 3213 \fB競合の回避\fR: 固有の名前空間を作成するには、パッケージに使用されている\fIcom\&.mycompany\&.todo\fRという名前のように、ドットで区切られた名前を使用します。Oracleは、今後も名前にドットを含まない標準タグを作成します。ユーザーが作成したタグは、Oracleが定義する同じ名前のタグの動作をオーバーライドします。\fI@todo\fRという名前のタグまたはタグレットをユーザーが作成した場合、その後にOracleが同じ名前の標準タグを作成しても、そのタグまたはタグレットは常にユーザーが定義したのと同じ動作を保持します。 3214 .sp 3215 \fB注釈vs\&. Javadocタグ\fR: 一般に、追加する必要のあるマークアップが、ドキュメントに影響を与えたりドキュメントを生成したりするためのものである場合、そのマークアップはJavadocタグにします。それ以外の場合は注釈にします。JavadocツールでのDocコメントの記述方法のカスタム・タグと注釈に関する項 3216 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html#annotations)を参照してください。 3217 .sp 3218 \fI\-taglet\fRオプションを使用して、より複雑なブロック・タグやカスタム・インライン・タグも作成できます。 3219 .RE 3220 .PP 3221 \-taglet \fIclass\fR 3222 .RS 4 3223 そのタグのドキュメントの生成に使用するドックレットを起動するためのクラス・ファイルを指定します。\fIclass\fR値の完全修飾名を使用します。このタグレットは、カスタム・タグのテキスト引数の数も定義します。タグレットは、これらの引数を受け付け、処理し、出力を生成します。タグレットの例を使用した豊富なドキュメントについては、タグレットの概要 3224 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/taglet/overview\&.html)を参照してください。 3225 .sp 3226 タグレットは、ブロックタグまたはインライン・タグで便利です。タグレットは任意の数の引数をとることができます。また、テキストを太字にする、箇条書きを作成する、テキストをファイルに書き出す、その他のプロセスを開始するなどのカスタム動作を実装できます。タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガーするなどの副作用は得られます。タグレットへのパスを指定するには、\fI\-tagletpath\fRオプションを使用します。次に、生成されるページのParametersとThrowsの間にTo Doタグレットを挿入する例を示します。または、\fI\-taglet\fRオプションをその\fI\-tag\fRオプションのかわりに使用することができますが、読み取りが困難になる可能性があります。 3227 .sp 3228 .if n \{\ 3229 .RS 4 3230 .\} 3231 .nf 3232 \-taglet com\&.sun\&.tools\&.doclets\&.ToDoTaglet 3233 \-tagletpath /home/taglets 3234 \-tag return 3235 \-tag param 3236 \-tag todo 3237 \-tag throws 3238 \-tag see 3239 .fi 3240 .if n \{\ 3241 .RE 3242 .\} 3243 .RE 3244 .PP 3245 \-tagletpath \fItagletpathlist\fR 3246 .RS 4 3247 tagletクラス・ファイルを検索するための検索パスを指定します。\fItagletpathlist\fRには、コロン(:)で区切って複数のパスを含めることができます。\fIjavadoc\fRコマンドは、指定されたパス以下のすべてのサブディレクトリを検索します。 3248 .RE 3249 .PP 3250 \-docfilesubdirs 3251 .RS 4 3252 doc\-filesディレクトリのディープ・コピーを有効にします。宛先には、サブディレクトリとそのすべて内容が再帰的にコピーされます。たとえば、ディレクトリoc\-files/example/imagesとその内容がすべてコピーされます。ここでも、サブディレクトリを除外する指定が可能です。 3253 .RE 3254 .PP 3255 \-excludedocfilessubdir \fIname1:name2\fR 3256 .RS 4 3257 指定された名前のdoc\-filesサブディレクトリをすべて除外します。これにより、SCCSとその他のソース・コード制御サブディレクトリのコピーを防ぎます。 3258 .RE 3259 .PP 3260 \-noqualifier all | \fIpackagename1\fR:\fIpackagename2\&.\&.\&.\fR 3261 .RS 4 3262 出力されるクラス名から修飾パッケージ名を省略します。\fI\-noqualifier\fRオプションの引数は、\fIall\fR(すべてのパッケージ修飾子を省略)、または修飾子として削除するパッケージのコロン区切りリスト(ワイルドカードも可)、のいずれかとなります。クラスまたはインタフェース名が表示される位置からパッケージ名が削除されます。ソース・ファイルの処理を参照してください。 3263 .sp 3264 次の例では、すべてのパッケージ修飾子を省略します。\fI\-noqualifier all\fR 3265 .sp 3266 次の例では、\fIjava\&.lang\fRおよび\fIjava\&.io\fRパッケージ修飾子を省略します: 3267 \fI\-noqualifier java\&.lang:java\&.io\fR。 3268 .sp 3269 次の例では、\fIjava\fRで始まるパッケージ修飾子および\fIcom\&.sun\fRサブパッケージを省略しますが、\fIjavax\fRは省略しません。\fI\-noqualifier java\&.*:com\&.sun\&.*\fR 3270 .sp 3271 パッケージ修飾子が前述の動作に従って表示される場合、名前は適切に短縮されます。「名前が表示される方法」を参照してください。このルールは、\fI\-noqualifier\fRオプションを使用するかどうかにかかわらず有効です。 3272 .RE 3273 .PP 3274 \-notimestamp 3275 .RS 4 3276 タイムスタンプが抑制されます。各ページの先頭近くにある、生成されたHTML内のHTMLコメントでタイムスタンプが隠されます。\fI\-notimestamp\fRオプションは、\fIjavadoc\fRコマンドを2つのソース・ベースで実行し、それらの間の差分\fIdiff\fRを取得する場合に役立ちます。タイムスタンプによる\fIdiff\fRの発生を防ぐからです(そうでないとすべてのページで\fIdiff\fRになります)。タイムスタンプには\fIjavadoc\fRコマンドのリリース番号が含まれ、現在では、\fI<!\-\- Generated by javadoc (build 1\&.5\&.0_01) on Thu Apr 02 14:04:52 IST 2009 \-\->\fRのように表示されます。 3277 .RE 3278 .PP 3279 \-nocomment 3280 .RS 4 3281 主説明およびすべてのタグを含むコメント本文全体を抑制し、宣言のみを生成します。このオプションにより、元は異なる目的のためだったソース・ファイルを再利用し、新しいプロジェクトの早い段階でスケルトンHTMLドキュメントを作成できるようになります。 3282 .RE 3283 .PP 3284 \-sourcetab \fItablength\fR 3285 .RS 4 3286 ソース内で各タブが使用する空白文字の数を指定します。 3287 .RE 3288 .SH "コマンドライン引数ファイル" 3289 .PP 3290 \fIjavadoc\fRコマンドを短くしたり簡潔にしたりするために、\fIjavadoc\fRコマンドに対する引数(\fI\-J\fRオプションを除く)が入った1つ以上のファイルを指定することができます。このことを利用すれば、どのオペレーティング・システム上でも、任意の長さの\fIjavadoc\fRコマンドを作成できます。 3291 .PP 3292 引数ファイルには、\fIjavac\fRのオプションとソース・ファイル名を自由に組み合せて記述できます。ファイル内の各引数は、スペースまたは改行で区切ります。ファイル名に埋め込まれた空白がある場合、ファイル名全体を二重引用符で囲みます。 3293 .PP 3294 引数ファイル内のファイル名は、引数ファイルの位置ではなく、現在のディレクトリに相対的となります。これらのリストでは、ワイルドカード(\fI*\fR)は使用できません。たとえば、*\&.javaとは指定できません。アットマーク(@)を使用して、ファイルを再帰的に解釈することはできません。また、\fI\-J\fRオプションもサポートされていません。このオプションは起動ツールに渡されますが、起動ツールでは引数ファイルをサポートしていないからです。 3295 .PP 3296 \fIjavadoc\fRを実行するときに、各引数ファイルのパスとファイル名の先頭に@文字を付けて渡します。\fIjavadoc\fRコマンドは、アットマーク(@)文字で始まる引数を見つけると、そのファイルの内容を展開して引数リストに挿入します。 3297 .PP 3298 \fBExample 1\fR, 単一の引数ファイル 3299 .RS 4 3300 \fIargfile\fRという名前の1つの引数ファイルを使用して、すべての\fIjavadoc\fRコマンド引数を保持できます。\fIjavadoc @argfile\fR次の例に示すように、この引数ファイルには両方のファイルの内容が含まれています。 3301 .RE 3302 .PP 3303 \fBExample 2\fR, 2つの引数ファイル 3304 .RS 4 3305 次のように、2つの引数ファイルを作成できます。\fIjavadoc\fRコマンドのオプション用に1つ、パッケージ名またはソース・ファイル名用に1つです。次のリストでは行継続文字を使用していません。 3306 .sp 3307 次の内容を含む、optionsという名前のファイルを作成します。 3308 .sp 3309 .if n \{\ 3310 .RS 4 3311 .\} 3312 .nf 3313 \-d docs\-filelist 3314 \-use 3315 \-splitindex 3316 \-windowtitle \*(AqJava SE 7 API Specification\*(Aq 3317 \-doctitle \*(AqJava SE 7 API Specification\*(Aq 3318 \-header \*(Aq<b>Java(TM) SE 7</b>\*(Aq 3319 \-bottom \*(AqCopyright © 1993\-2011 Oracle and/or its affiliates\&. All rights reserved\&.\*(Aq 3320 \-group "Core Packages" "java\&.*" 3321 \-overview /java/pubs/ws/1\&.7\&.0/src/share/classes/overview\-core\&.html 3322 \-sourcepath /java/pubs/ws/1\&.7\&.0/src/share/classes 3323 .fi 3324 .if n \{\ 3325 .RE 3326 .\} 3327 次の内容を含む、packagesという名前のファイルを作成します。 3328 .sp 3329 .if n \{\ 3330 .RS 4 3331 .\} 3332 .nf 3333 com\&.mypackage1 3334 com\&.mypackage2 3335 com\&.mypackage3 3336 .fi 3337 .if n \{\ 3338 .RE 3339 .\} 3340 次のように、\fIjavadoc\fRコマンドを実行します。 3341 .sp 3342 .if n \{\ 3343 .RS 4 3344 .\} 3345 .nf 3346 javadoc @options @packages 3347 .fi 3348 .if n \{\ 3349 .RE 3350 .\} 3351 .RE 3352 .PP 3353 \fBExample 3\fR, パスを使用した引数ファイル 3354 .RS 4 3355 引数ファイルはパスを指定できますが、ファイル内のすべてのファイル名は、(\fIpath1\fRや\fIpath2\fRではなく)次のように現在の作業ディレクトリに相対的となります。 3356 .sp 3357 .if n \{\ 3358 .RS 4 3359 .\} 3360 .nf 3361 javadoc @path1/options @path2/packages 3362 .fi 3363 .if n \{\ 3364 .RE 3365 .\} 3366 .RE 3367 .PP 3368 \fBExample 4\fR, オプション引数 3369 .RS 4 3370 次に、\fIjavadoc\fRコマンドのオプションに対する引数を引数ファイルに格納する例を示します。長い引数を指定できるので、\fI\-bottom\fRオプションを使用します。次のようなテキスト引数を含む、bottomという名前のファイルを作成できます。 3371 .sp 3372 .if n \{\ 3373 .RS 4 3374 .\} 3375 .nf 3376 <font size="\-1"> 3377 <a href="http://bugreport\&.sun\&.com/bugreport/">Submit a bug or feature</a><br/> 3378 Copyright © 1993, 2011, Oracle and/or its affiliates\&. All rights reserved\&. <br/> 3379 Oracle is a registered trademark of Oracle Corporation and/or its affiliates\&. 3380 Other names may be trademarks of their respective owners\&.</font> 3381 .fi 3382 .if n \{\ 3383 .RE 3384 .\} 3385 \fIjavadoc\fRコマンドを次のように実行します。\fI javadoc \-bottom @bottom @packages\fR 3386 .sp 3387 \fI\-bottom\fRオプションを引数ファイルの最初に含めて、次のように\fIjavadoc\fRコマンドを実行することもできます。\fIjavadoc @bottom @packages\fR 3388 .RE 3389 .SH "JAVADOCコマンドの実行" 3390 .PP 3391 \fIjavadoc\fRコマンドのリリース番号は\fIjavadoc \-J\-version\fRオプションで特定できます。出力ストリームには標準ドックレットのリリース番号が含まれます。\fI\-quiet\fRオプションで無効にできます。 3392 .PP 3393 Java言語で記述されたプログラムから\fIjavadoc\fRコマンドを起動するには公開プログラマティック・インタフェースを使用します。このインタフェースは\fIcom\&.sun\&.tools\&.javadoc\&.Main\fRにあります(また\fIjavadoc\fRコマンドは再入可能です)。詳細は、標準ドックレット 3394 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/standard\-doclet\&.html#runningprogrammatically)を参照してください。 3395 .PP 3396 次の手順では、標準HTMLドックレットを呼び出します。カスタム・ドックレットを呼び出すには、\fI\-doclet\fRおよび\fI\-docletpath\fRオプションを使用しますドックレットの概要 3397 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/doclet/overview\&.html)を参照してください 3398 .SS "簡単な例" 3399 .PP 3400 \fIjavadoc\fRコマンドは、パッケージ全体に対して実行することも、個々のソース・ファイルに対して実行することもできます。各パッケージ名は、それぞれのパッケージ名に対応するディレクトリ名を持ちます。 3401 .PP 3402 次の例では、ソース・ファイルは/home/src/java/awt/*\&.javaにあります。生成先ディレクトリは/home/htmlです。 3403 1つ以上のパッケージのドキュメント化.PP 3404 パッケージをドキュメント化するには、そのパッケージのソース・ファイルを、そのパッケージと同じ名前のディレクトリ内に格納する必要があります。 3405 .PP 3406 パッケージ名が(\fIjava\&.awt\&.color\fRのようにドットで区切られた)複数の識別子から構成されている場合、後続の各識別子が下位のサブディレクトリ(ava/awt/colorなど)に対応している必要があります。 3407 .PP 3408 1つのパッケージのための複数のソース・ファイルを、異なる場所にあるそのような2つのディレクトリ・ツリーに分けて格納することもできます。ただし、その場合は\fI\-sourcepath\fRによってその両方の場所を指定する必要があります。たとえば、src1/java/awt/colorとsrc2/java/awt/color。 3409 .PP 3410 ディレクトリの変更(\fIcd\fRコマンドを使用)または\fI\-sourcepath\fRオプションにより、\fIjavadoc\fRコマンドを実行できます。次の例で両方の選択肢を示します。 3411 .PP 3412 \fBExample 1\fR, 1つ以上のパッケージから再帰的に実行 3413 .RS 4 3414 この例では\fIjavadoc\fRコマンドが任意のディレクトリから実行できるように、\fI\-sourcepath\fRを使用し、再帰的処理のために\fI\-subpackages\fR 3415 (1\&.4の新オプション)を使用します。これは、javaディレクトリのサブパッケージをたどりますが、\fIjava\&.net\fRと\fIjava\&.lang\fRをルートに持つパッケージは除外されます。\fIjava\&.lang\fRのサブパッケージである\fIjava\&.lang\&.ref\fRが除外される点に注意してください。また、他のパッケージ・ツリーを下方にたどるには、\fIjava:javax:org\&.xml\&.sax\fRのように、それらのパッケージの名前を\fI\-subpackages\fRの引数に追加します。 3416 .sp 3417 .if n \{\ 3418 .RS 4 3419 .\} 3420 .nf 3421 javadoc \-d /home/html \-sourcepath /home/src \-subpackages java \-exclude 3422 .fi 3423 .if n \{\ 3424 .RE 3425 .\} 3426 .RE 3427 .PP 3428 \fBExample 2\fR, ルートへの移動および明示的なパッケージの実行 3429 .RS 4 3430 完全修飾されたパッケージの親ディレクトリに移動します。次に、ドキュメント化する1つ以上のパッケージの名前を指定して\fIjavadoc\fRコマンドを実行します。 3431 .sp 3432 .if n \{\ 3433 .RS 4 3434 .\} 3435 .nf 3436 cd /home/src/ 3437 javadoc \-d /home/html java\&.awt java\&.awt\&.event 3438 .fi 3439 .if n \{\ 3440 .RE 3441 .\} 3442 また、他のパッケージ・ツリーを下方にたどるには、j\fIava:javax:org\&.xml\&.sax\fRのように、それらのパッケージの名前を\fI\-subpackages\fRの引数に追加します。 3443 .RE 3444 .PP 3445 \fBExample 3\fR, 1つのツリーの明示的なパッケージの任意のディレクトリから実行 3446 .RS 4 3447 この場合、現在のディレクトリがどこかは問題ではありません。\fIjavadoc\fRコマンドを実行し、最上位パッケージの親ディレクトリを指定して\fI\-sourcepath\fRオプションを使用します。ドキュメント化する1つ以上のパッケージの名前を指定します。 3448 .sp 3449 .if n \{\ 3450 .RS 4 3451 .\} 3452 .nf 3453 javadoc \-d /home/html \-sourcepath /home/src java\&.awt java\&.awt\&.event 3454 .fi 3455 .if n \{\ 3456 .RE 3457 .\} 3458 .RE 3459 .PP 3460 \fBExample 4\fR, 複数のツリーの明示的なパッケージの任意のディレクトリから実行 3461 .RS 4 3462 \fIjavadoc\fRコマンドを実行し、各ツリーのルートへのパスのコロン区切りリストを指定して\fI\-sourcepath\fRオプションを使用します。ドキュメント化する1つ以上のパッケージの名前を指定します。指定したパッケージのすべてのソース・ファイルが、1つのルート・ディレクトリの下に存在する必要はありませんが、ソース・パスで指定された場所のどこかで見つかる必要があります。 3463 .sp 3464 .if n \{\ 3465 .RS 4 3466 .\} 3467 .nf 3468 javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java\&.awt java\&.awt\&.event 3469 .fi 3470 .if n \{\ 3471 .RE 3472 .\} 3473 すべてのケースでj\fIava\&.awt\fRおよび\fIjava\&.awt\&.even\fRtパッケージ内の\fIpublic\fRおよび\fIprotected\fRクラスとインタフェースについて、HTML形式のドキュメントが生成され、指定された生成先ディレクトリにHTMLファイルが保存されます。2つ以上のパッケージが生成されているので、ドキュメントは、パッケージのリスト、クラスのリスト、およびメインのクラス・ページという3つのHTMLフレームを持つことになります。 3474 .RE 3475 1つ以上のクラスのドキュメント化.PP 3476 また、1つ以上のソース・ファイルを渡して、\fIjavadoc\fRコマンドを実行することもできます。\fIjavadoc\fRは、次の2つの方法のいずれかで実行できます。1つはディレクトリを変更する方法(\fIcd\fRを使用)、もう1つはソース・ファイルへのパスを完全に指定する方法です。相対パスは、現在のディレクトリを起点とします。ソース・ファイルを渡すときは、\fI\-sourcepath\fRオプションは無視されます。アスタリスク(*)のようなコマンドライン・ワイルドカードを使用すると、クラスのグループを指定できます。 3477 .PP 3478 \fBExample 1\fR, ソース・ディレクトリに変更 3479 .RS 4 3480 ソースを保持するディレクトリに変更します。次に、ドキュメント化する1つ以上のソース・ファイルの名前を指定して\fIjavadoc\fRコマンドを実行します。 3481 .sp 3482 この例では、\fIButton\fRクラスと\fICanvas\fRクラス、および名前が\fIGraphics\fRで始まるクラスについて、HTML形式のドキュメントが生成されます。パッケージ名ではなくソース・ファイルが\fIjavadoc\fRコマンドに引数として渡されているので、ドキュメントは、クラスのリストとメイン・ページという2つのフレームを持つことになります。 3483 .sp 3484 .if n \{\ 3485 .RS 4 3486 .\} 3487 .nf 3488 cd /home/src/java/awt 3489 javadoc \-d /home/html Button\&.java Canvas\&.java Graphics*\&.java 3490 .fi 3491 .if n \{\ 3492 .RE 3493 .\} 3494 .RE 3495 .PP 3496 \fBExample 2\fR, パッケージのルート・ディレクトリに変更 3497 .RS 4 3498 これは、同じルートからの別のサブパッケージの個々のソース・ファイルをドキュメント化するのに役立ちます。パッケージのルート・ディレクトリに移り、各ソース・ファイルを、ルートからのパスとともに指定します。 3499 .sp 3500 .if n \{\ 3501 .RS 4 3502 .\} 3503 .nf 3504 cd /home/src/ 3505 javadoc \-d /home/html java/awt/Button\&.java java/applet/Applet\&.java 3506 .fi 3507 .if n \{\ 3508 .RE 3509 .\} 3510 .RE 3511 .PP 3512 \fBExample 3\fR, 任意のディレクトリからのファイルのドキュメント化 3513 .RS 4 3514 この場合、現在のディレクトリがどこかは問題ではありません。ドキュメント化するソース・ファイルへの絶対パス(または現在のディレクトリからの相対パス)を指定して\fIjavadoc\fRコマンドを実行します。 3515 .sp 3516 .if n \{\ 3517 .RS 4 3518 .\} 3519 .nf 3520 javadoc \-d /home/html /home/src/java/awt/Button\&.java 3521 /home/src/java/awt/Graphics*\&.java 3522 .fi 3523 .if n \{\ 3524 .RE 3525 .\} 3526 .RE 3527 パッケージおよびクラスのドキュメント化.PP 3528 パッケージ全体と個々のクラスを同時に指定してドキュメント化することもできます。次に、前述の2つの例を組み合せた例を示します。\fI\-sourcepath\fRオプションは、パッケージへのパスに対しては使用できますが、個々のクラスへのパスに対しては使用できません。 3529 .sp 3530 .if n \{\ 3531 .RS 4 3532 .\} 3533 .nf 3534 javadoc \-d /home/html \-sourcepath /home/src java\&.awt 3535 /home/src/java/applet/Applet\&.java 3536 .fi 3537 .if n \{\ 3538 .RE 3539 .\} 3540 .SS "実際の例" 3541 .PP 3542 次のコマンドラインおよび\fImakefile\fRバージョンの\fIjavadoc\fRコマンドをJavaプラットフォームAPIで実行します。Java SE 1\&.2で約1500個のpublicおよびprotectedクラスのドキュメントを生成するには、180MBのメモリーを使用します。どちらの例もオプションの引数で絶対パスが使用されているため、任意のディレクトリから同じ\fIjavadoc\fRコマンドを実行できます。 3543 コマンドラインの例.PP 3544 次のコマンドは、一部のシェルに対して長すぎる可能性があります。この制限を回避するには、コマンドライン引数ファイルを使用します。または、シェル・スクリプトを記述します。 3545 .PP 3546 この例では、\fIpackages\fRは処理するパッケージを含む名前で、\fIjava\&.applet\fR 3547 \fIjava\&.lang\fRなどです。各オプションの、一重引用符で囲まれた引数の内側には、改行文字を挿入できません。たとえば、この例をコピー・アンド・ペーストする場合は、\fI\-bottom\fRオプションから改行文字を削除してください。 3548 .sp 3549 .if n \{\ 3550 .RS 4 3551 .\} 3552 .nf 3553 javadoc \-sourcepath /java/jdk/src/share/classes \e 3554 \-overview /java/jdk/src/share/classes/overview\&.html \e 3555 \-d /java/jdk/build/api \e 3556 \-use \e 3557 \-splitIndex \e 3558 \-windowtitle \*(AqJava Platform, Standard Edition 7 API Specification\*(Aq \e 3559 \-doctitle \*(AqJava Platform, Standard Edition 7 API Specification\*(Aq \e 3560 \-header \*(Aq<b>Java(TM) SE 7</b>\*(Aq \e 3561 \-bottom \*(Aq<font size="\-1"> 3562 <a href="http://bugreport\&.sun\&.com/bugreport/">Submit a bug or feature</a><br/> 3563 Copyright © 1993, 2011, Oracle and/or its affiliates\&. All rights reserved\&.<br/> 3564 Oracle is a registered trademark of Oracle Corporation and/or its affiliates\&. 3565 Other names may be trademarks of their respective owners\&.</font>\*(Aq \e 3566 \-group "Core Packages" "java\&.*:com\&.sun\&.java\&.*:org\&.omg\&.*" \e 3567 \-group "Extension Packages" "javax\&.*" \e 3568 \-J\-Xmx180m \e 3569 @packages 3570 .fi 3571 .if n \{\ 3572 .RE 3573 .\} 3574 プログラマティック・インタフェース.PP 3575 Javadoc Access APIでは、新しいプロセスを実行しなくても、JavadocツールをJavaアプリケーションから直接起動できます。 3576 .PP 3577 たとえば、次の文はコマンド\fIjavadoc \-d /home/html \-sourcepath /home/src \-subpackages java \-exclude java\&.net:java\&.lang com\&.example\fRと同等です。 3578 .sp 3579 .if n \{\ 3580 .RS 4 3581 .\} 3582 .nf 3583 import javax\&.tools\&.DocumentationTool; 3584 import javax\&.tools\&.ToolProvider; 3585 3586 public class JavaAccessSample{ 3587 public static void main(String[] args){ 3588 DocumentationTool javadoc = ToolProvider\&.getSystemDocumentationTool(); 3589 int rc = javadoc\&.run( null, null, null, 3590 "\-d", "/home/html", 3591 "\-sourcepath", "home/src", 3592 "\-subpackages", "java", 3593 "\-exclude", "java\&.net:java\&.lang", 3594 "com\&.example"); 3595 } 3596 } 3597 .fi 3598 .if n \{\ 3599 .RE 3600 .\} 3601 .PP 3602 \fIrun\fRメソッドの最初の3つの引数は、入力、標準出力、および標準エラー・ストリームを指定します。\fINull\fRは\fISystem\&.in\fR、\fISystem\&.out\fRおよび\fISystem\&.err\fRそれぞれのデフォルト値です。 3603 .SS "makefileの例" 3604 .PP 3605 ここでは、GNU 3606 \fImakefile\fRの例を示します。\fImakefile\fRの引数は、一重引用符で囲みます。Windows 3607 \fImakefile\fRの例については、Javadoc FAQの\fImakefiles\fRに関する項 3608 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137483\&.html#makefiles)を参照してください 3609 .sp 3610 .if n \{\ 3611 .RS 4 3612 .\} 3613 .nf 3614 javadoc \-sourcepath $(SRCDIR) \e /* Sets path for source files */ 3615 \-overview $(SRCDIR)/overview\&.html \e /* Sets file for overview text */ 3616 \-d /java/jdk/build/api \e /* Sets destination directory */ 3617 \-use \e /* Adds "Use" files */ 3618 \-splitIndex \e /* Splits index A\-Z */ 3619 \-windowtitle $(WINDOWTITLE) \e /* Adds a window title */ 3620 \-doctitle $(DOCTITLE) \e /* Adds a doc title */ 3621 \-header $(HEADER) \e /* Adds running header text */ 3622 \-bottom $(BOTTOM) \e /* Adds text at bottom */ 3623 \-group $(GROUPCORE) \e /* 1st subhead on overview page */ 3624 \-group $(GROUPEXT) \e /* 2nd subhead on overview page */ 3625 \-J\-Xmx180m \e /* Sets memory to 180MB */ 3626 java\&.lang java\&.lang\&.reflect \e /* Sets packages to document */ 3627 java\&.util java\&.io java\&.net \e 3628 java\&.applet 3629 3630 WINDOWTITLE = \*(AqJava(TM) SE 7 API Specification\*(Aq 3631 DOCTITLE = \*(AqJava(TM) Platform Standard Edition 7 API Specification\*(Aq 3632 HEADER = \*(Aq<b>Java(TM) SE 7</font>\*(Aq 3633 BOTTOM = \*(Aq<font size="\-1"> 3634 <a href="http://bugreport\&.sun\&.com/bugreport/">Submit a bug or feature</a><br/> 3635 Copyright © 1993, 2011, Oracle and/or its affiliates\&. All rights reserved\&.<br/> 3636 Oracle is a registered trademark of Oracle Corporation and/or its affiliates\&. 3637 Other names may be trademarks of their respective owners\&.</font>\*(Aq 3638 GROUPCORE = \*(Aq"Core Packages" "java\&.*:com\&.sun\&.java\&.*:org\&.omg\&.*"\*(Aq 3639 GROUPEXT = \*(Aq"Extension Packages" "javax\&.*"\*(Aq 3640 SRCDIR = \*(Aq/java/jdk/1\&.7\&.0/src/share/classes\*(Aq 3641 .fi 3642 .if n \{\ 3643 .RE 3644 .\} 3645 .SS "注意" 3646 .sp 3647 .RS 4 3648 .ie n \{\ 3649 \h'-04'\(bu\h'+03'\c 3650 .\} 3651 .el \{\ 3652 .sp -1 3653 .IP \(bu 2.3 3654 .\} 3655 \fI\-windowtitle\fRオプションを省略すると、\fIjavadoc\fRコマンドによってドキュメント・タイトルがウィンドウ・タイトルにコピーされます。\fI\-windowtitle\fRオプションのテキストは、\fI\-doctitle\fRオプションと同じですが、HTMLタグは含まれません。これは、HTMLタグが、ウィンドウ・タイトル内にそのままのテキストとして表示されるのを防ぐためです。 3656 .RE 3657 .sp 3658 .RS 4 3659 .ie n \{\ 3660 \h'-04'\(bu\h'+03'\c 3661 .\} 3662 .el \{\ 3663 .sp -1 3664 .IP \(bu 2.3 3665 .\} 3666 \fI\-footer\fRオプションを省略すると、\fIjavadoc\fRコマンドによってヘッダー・テキストがフッターにコピーされます。 3667 .RE 3668 .sp 3669 .RS 4 3670 .ie n \{\ 3671 \h'-04'\(bu\h'+03'\c 3672 .\} 3673 .el \{\ 3674 .sp -1 3675 .IP \(bu 2.3 3676 .\} 3677 この例では必要ありませんが、\fI\-classpath\fRと\fI\-link\fRも重要なオプションです。 3678 .RE 3679 .SH "一般的なトラブルシューティング" 3680 .sp 3681 .RS 4 3682 .ie n \{\ 3683 \h'-04'\(bu\h'+03'\c 3684 .\} 3685 .el \{\ 3686 .sp -1 3687 .IP \(bu 2.3 3688 .\} 3689 \fIjavadoc\fRコマンドは有効なクラス名を含むファイルのみを読み取ります。\fIjavadoc\fRコマンドがファイルの内容を正しく読み取っていない場合は、クラス名が有効であることを確認します。ソース・ファイルの処理を参照してください。 3690 .RE 3691 .sp 3692 .RS 4 3693 .ie n \{\ 3694 \h'-04'\(bu\h'+03'\c 3695 .\} 3696 .el \{\ 3697 .sp -1 3698 .IP \(bu 2.3 3699 .\} 3700 共通の不具合およびトラブルシューティングのヒントについては、Javadoc FAQ 3701 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137483\&.html)を参照してください。 3702 .RE 3703 .SH "エラーと警告" 3704 .PP 3705 エラーおよび警告メッセージには、ファイル名と宣言行(ドキュメンテーション・コメント内の特定の行ではない)の行番号が含まれます。 3706 .PP 3707 たとえば、メッセージ\fI「エラー: Class1\&.javaを読み込めません」\fRは、\fIjavadoc\fRコマンドが\fIClass1\&.jav\fR\fIa\fRを現在のディレクトリにロードしようとしていることを意味します。クラス名はそのパス(絶対または相対)で表示されます。 3708 .SH "環境" 3709 .PP 3710 CLASSPATH 3711 .RS 4 3712 \fICLASSPATH\fRは、\fIjavadoc\fRコマンドがユーザー・クラス・ファイルの検出に使用するパスを提供する環境変数です。この環境変数は、\fI\-classpath\fRオプションによってオーバーライドされます。ディレクトリはセミコロン(Windowsの場合)またはコロン(Oracle Solarisの場合)で区切ります。 3713 .sp 3714 \fBWindowsの例\fR: 3715 \fI\&.;C:\eclasses;C:\ehome\ejava\eclasses\fR 3716 .sp 3717 \fBOracle Solarisの例\fR: 3718 \fI\&.:/home/classes:/usr/local/java/classes\fR 3719 .RE 3720 .SH "関連項目" 3721 .sp 3722 .RS 4 3723 .ie n \{\ 3724 \h'-04'\(bu\h'+03'\c 3725 .\} 3726 .el \{\ 3727 .sp -1 3728 .IP \(bu 2.3 3729 .\} 3730 javac(1) 3731 .RE 3732 .sp 3733 .RS 4 3734 .ie n \{\ 3735 \h'-04'\(bu\h'+03'\c 3736 .\} 3737 .el \{\ 3738 .sp -1 3739 .IP \(bu 2.3 3740 .\} 3741 java(1) 3742 .RE 3743 .sp 3744 .RS 4 3745 .ie n \{\ 3746 \h'-04'\(bu\h'+03'\c 3747 .\} 3748 .el \{\ 3749 .sp -1 3750 .IP \(bu 2.3 3751 .\} 3752 jdb(1) 3753 .RE 3754 .sp 3755 .RS 4 3756 .ie n \{\ 3757 \h'-04'\(bu\h'+03'\c 3758 .\} 3759 .el \{\ 3760 .sp -1 3761 .IP \(bu 2.3 3762 .\} 3763 javah(1) 3764 .RE 3765 .sp 3766 .RS 4 3767 .ie n \{\ 3768 \h'-04'\(bu\h'+03'\c 3769 .\} 3770 .el \{\ 3771 .sp -1 3772 .IP \(bu 2.3 3773 .\} 3774 javap(1) 3775 .RE 3776 .SH "関連ドキュメント" 3777 .sp 3778 .RS 4 3779 .ie n \{\ 3780 \h'-04'\(bu\h'+03'\c 3781 .\} 3782 .el \{\ 3783 .sp -1 3784 .IP \(bu 2.3 3785 .\} 3786 Javadocテクノロジ 3787 (http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/index\&.html) 3788 .RE 3789 .sp 3790 .RS 4 3791 .ie n \{\ 3792 \h'-04'\(bu\h'+03'\c 3793 .\} 3794 .el \{\ 3795 .sp -1 3796 .IP \(bu 2.3 3797 .\} 3798 クラスの検出方法 3799 (http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html) 3800 .RE 3801 .sp 3802 .RS 4 3803 .ie n \{\ 3804 \h'-04'\(bu\h'+03'\c 3805 .\} 3806 .el \{\ 3807 .sp -1 3808 .IP \(bu 2.3 3809 .\} 3810 JavadocツールでのDocコメントの記述方法 3811 (http://www\&.oracle\&.com/technetwork/java/javase/documentation/index\-137868\&.html) 3812 .RE 3813 .sp 3814 .RS 4 3815 .ie n \{\ 3816 \h'-04'\(bu\h'+03'\c 3817 .\} 3818 .el \{\ 3819 .sp -1 3820 .IP \(bu 2.3 3821 .\} 3822 URLメモ、Uniform Resource Locators 3823 (http://www\&.ietf\&.org/rfc/rfc1738\&.txt) 3824 .RE 3825 .sp 3826 .RS 4 3827 .ie n \{\ 3828 \h'-04'\(bu\h'+03'\c 3829 .\} 3830 .el \{\ 3831 .sp -1 3832 .IP \(bu 2.3 3833 .\} 3834 HTML標準、HTML Document Representation (4197265および4137321) 3835 (http://www\&.w3\&.org/TR/REC\-html40/charset\&.html#h\-5\&.2\&.2) 3836 .RE 3837 .br 3838 'pl 8.5i 3839 'bp |