|
1 '\" t |
|
2 .\" |
|
3 .\" Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. |
|
4 .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
5 .\" |
|
6 .\" This code is free software; you can redistribute it and/or modify it |
|
7 .\" under the terms of the GNU General Public License version 2 only, as |
|
8 .\" published by the Free Software Foundation. |
|
9 .\" |
|
10 .\" This code is distributed in the hope that it will be useful, but WITHOUT |
|
11 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
12 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
13 .\" version 2 for more details (a copy is included in the LICENSE file that |
|
14 .\" accompanied this code). |
|
15 .\" |
|
16 .\" You should have received a copy of the GNU General Public License version |
|
17 .\" 2 along with this work; if not, write to the Free Software Foundation, |
|
18 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
19 .\" |
|
20 .\" Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
21 .\" CA 95054 USA or visit www.sun.com if you need additional information or |
|
22 .\" have any questions. |
|
23 .\" |
|
24 .\" |
|
25 .TH javadoc 1 "2006 年 9 月 4 日" "Java SE 6" "ユーザーコマンド" |
|
26 .hw javadoc |
|
27 .SH "名前" |
|
28 javadoc \- Java API ドキュメントジェネレータ |
|
29 .RS 3 |
|
30 |
|
31 .LP |
|
32 .LP |
|
33 Java ソースファイルから、API ドキュメントの HTML ページを生成します。このドキュメントで紹介されている Javadoc の例は、Sun Solaris を使用した場合のものです。 |
|
34 .LP |
|
35 .SH "形式" |
|
36 .B javadoc |
|
37 [ |
|
38 .I options |
|
39 ] [ |
|
40 .I packagenames |
|
41 ] [ |
|
42 .I sourcefilenames |
|
43 ] [ |
|
44 .I \-subpackages pkg1:pkg2:... |
|
45 ] [ |
|
46 .I @argfiles |
|
47 ] |
|
48 .LP |
|
49 .LP |
|
50 引数を指定する順序は任意です。Javadoc ツールでの、処理対象の \f2.java\fP ファイルを決定する方法の詳細については、「ソースファイルの処理」を参照してください。 |
|
51 .TP 15 |
|
52 .I options |
|
53 このドキュメントで指定されているコマンド行オプションです。 |
|
54 .B javadoc |
|
55 のオプションの一般的な使用法については、「使用例」を参照してください。 |
|
56 .TP |
|
57 .I packagenames |
|
58 .BR "java.lang java.lang.reflect java.awt" |
|
59 などの、スペースで区切られた |
|
60 一連のパッケージ名です。ドキュメント化するパッケージごとに別個に |
|
61 指定する必要があります。 |
|
62 .B javadoc |
|
63 ツールはこれらのパッケージ名を探すとき、 |
|
64 .B \-sourcepath |
|
65 を使用します。 |
|
66 .B javadoc |
|
67 ツールは、サブパッケージを再帰的に処理することはありません。 |
|
68 アスタリスク (\f3*\f1) などのワイルドカードは使うことができません。 |
|
69 「1 つ以上のパッケージのドキュメント化」の |
|
70 例を参照してください。 |
|
71 .TP |
|
72 .I sourcefilenames |
|
73 スペースで区切られた一連のファイル名です。パス、および |
|
74 アスタリスク (\f3*\f1) などのワイルドカードを含めることができます。 |
|
75 .B javadoc |
|
76 ツールが処理するのは、ファイル名が「.java」という拡張子で終わり、 |
|
77 その拡張子を除いた名前が実際に有効なクラス名 |
|
78 .fi |
|
79 (http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625 |
|
80 の |
|
81 .na |
|
82 「\f2Identifiers\fP」を参照) であるすべてのファイルです。 |
|
83 したがって、ハイフンを含む名前 (X-Buffer など) や、 |
|
84 その他の無効な文字を含む名前を付けることによって、 |
|
85 それらのファイルをドキュメント化の対象から除外できます。 |
|
86 これは、テスト用のファイルや、テンプレートから生成されたファイルの場合に便利です。 |
|
87 .B javadoc |
|
88 ツールは、ソースファイル名の前に指定されたパスを使用して、 |
|
89 ソースファイル名を探します。この場合、 |
|
90 .B -sourcepath |
|
91 は使用しません。たとえば、 |
|
92 .B Button.java |
|
93 を渡すことは |
|
94 .BR ./Button.java |
|
95 と指定することと同じです。完全パスを付けたソースファイル名の |
|
96 例は「 |
|
97 .BR /home/src/java/awt/Graphics*.java |
|
98 」のようになります。「1 つ以上のクラスのドキュメント化」の例を |
|
99 参照してください。また、「パッケージとクラスのドキュメント化」の |
|
100 例のように、パッケージ名とソースファイル名を組み合わせることもできます。 |
|
101 .TP |
|
102 .I \-subpackages pkg1:pkg2:... |
|
103 指定されたパッケージ内のソースファイルからドキュメントを生成し、 |
|
104 再帰的にサブパッケージを処理します。 パッケージ名または |
|
105 ソールファイル名を指定するための代替手段です。 |
|
106 .TP |
|
107 .I @argfiles |
|
108 Javadoc オプション、パッケージ名、およびソースファイル名を |
|
109 任意の順序で並べたリストが含まれる 1 つ以上のファイルです。 |
|
110 このファイルの中では、ワイルドカード (*) および |
|
111 .B \-J |
|
112 オプションは指定できません。 |
|
113 .SH "機能説明" |
|
114 .B javadoc |
|
115 ツールは、一連の Java ソースファイルの宣言およびドキュメント |
|
116 コメントを解析し、デフォルトでは public クラスと protected クラス、 |
|
117 入れ子クラス（匿名の内部クラスを除く）、インタフェース、コンストラクタ、メソッド、および |
|
118 フィールドについて説明した一連の HTML ページを生成します。また、API (アプリケーションプログラミングインタフェース) ドキュメントの生成や、一連のソースファイルの実装ドキュメントの生成に使用できます。 |
|
119 .LP |
|
120 .B javadoc |
|
121 ツールは、パッケージ全体、個々のソースファイル、またはその両方に対して |
|
122 実行できます。 |
|
123 .B javadoc |
|
124 ツールをパッケージ全体に対して実行する場合は、最上位ディレクトリから再帰的にたどるために -subpackages を使用するか、パッケージ名の明示的なリストを渡します。 |
|
125 個々のクラスに対して javadoc を実行する場合は、一連の |
|
126 ソース (\f3.java\f1) ファイル名を渡します。具体的な例は、 |
|
127 このページの最後で示します。 |
|
128 次に、Javadoc によるソースファイルの処理について説明します。 |
|
129 .LP |
|
130 .SS |
|
131 ソースファイルの処理 |
|
132 .LP |
|
133 .LP |
|
134 Javadoc ツールは、末尾に \f2.java\fP の付いたファイル以外に、ソースファイルで説明する他のファイルも処理します。個々のソースファイル名を明示的に渡すことによって Javadoc ツールを実行する場合、\f2.java\fP ファイルを処理するかを正確に指定できます。ただし、多くの開発者はこの方法では作業しません。パッケージ名を渡すほうが簡単だからです。ソースファイル名を明示的に指定しなくても、Javadoc ツールは 3 つの方法で実行できます。この方法は、(1) パッケージ名を渡す、(2) \f2\-subpackages\fP を使用する、(3) ソースファイル名にワイルドカードを使用する (\f2*.java\fP) という方法です。これらの方法を使用する場合、Javadoc ツールは、\f2*.java\fP ファイルが次のすべての要件を満たしている場合にかぎり、このファイルを処理します。 |
|
135 .LP |
|
136 .RS 3 |
|
137 .TP 2 |
|
138 o |
|
139 名前から \f2.java\fP の接尾辞を取り除くと、実際に有効なクラス名になっている (有効な文字については、 |
|
140 .fi |
|
141 http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625 |
|
142 の |
|
143 .na |
|
144 「\f2Identifiers\fP」を参照) |
|
145 .TP 2 |
|
146 o |
|
147 ソースツリーのルートから相対的なディレクトリパスが、区切り文字をドットに変換すると、実際に有効なパッケージ名になっている |
|
148 .TP 2 |
|
149 o |
|
150 パッケージ文には有効なパッケージ名が含まれる (前項目で指定) |
|
151 .RE |
|
152 |
|
153 .LP |
|
154 .LP |
|
155 \f3リンクの処理\fP \- |
|
156 実行時に、 |
|
157 .B javadoc |
|
158 ツールはその実行の一部として記述されているパッケージ、クラス、 |
|
159 およびメンバの名称にクロスリファレンスリンクを自動的に |
|
160 追加します。リンクは、次の箇所に現われます。 |
|
161 .LP |
|
162 .TP 2 |
|
163 \(bu |
|
164 宣言 (戻り値の型、引数の型、フィールドの型) |
|
165 .TP 2 |
|
166 \(bu |
|
167 @see タグから生成される [関連項目] のセクション |
|
168 .TP 2 |
|
169 \(bu |
|
170 {@link} タグから生成されるインラインテキスト |
|
171 .TP 2 |
|
172 \(bu |
|
173 @throws タグから生成される例外の名称 |
|
174 .TP 2 |
|
175 \(bu |
|
176 インタフェースのメンバに対する [定義] リンクと、クラスのメンバに対する [オーバーライド] リンク |
|
177 .TP 2 |
|
178 \(bu |
|
179 パッケージ、クラス、およびメンバを記述した一覧表 |
|
180 .TP 2 |
|
181 \(bu |
|
182 パッケージとクラスの継承ツリー |
|
183 .TP 2 |
|
184 \(bu |
|
185 索引 |
|
186 .LP |
|
187 \-link と \-linkoffline オプションを使用して、 |
|
188 コマンド行に含まれていない、個別に生成されるクラスの既存のテキストに |
|
189 ハイパーリンクを追加できます。 |
|
190 .LP |
|
191 \f3その他の処理についての詳細\fP \- |
|
192 javadoc ツールは、実行のたびにひとつの完全なドキュメントを生成します。javadoc は、 |
|
193 追加生成を行えません。つまり、以前に実行した javadoc の結果を変更したり、 |
|
194 それらを直接取り込むことはできません。しかし、前述のようにほかの |
|
195 実行の結果にリンクすることは可能です。 |
|
196 .LP |
|
197 実装上の理由から、 |
|
198 .B javadoc |
|
199 ツールは実行に java コンパイラを必要とし、java コンパイラに依存しています。 |
|
200 .B javadoc |
|
201 ツールは |
|
202 .B javac |
|
203 の一部を呼び出して、宣言をコンパイルし、メンバの実装は無視します。 |
|
204 .B javadoc |
|
205 ツールは、クラス階層を含むクラスの豊富な内部表現、および「使用」関係を |
|
206 構築し、そこから HTML を生成します。 |
|
207 .B javadoc |
|
208 ツールは、ソースコードのドキュメンテーションコメントから、ユーザの |
|
209 提供するドキュメントも取得します。 |
|
210 .LP |
|
211 .B javadoc |
|
212 ツールは、メソッド本体のない純粋なスタブファイルである |
|
213 .B .java |
|
214 ソースファイル上で実行されます。つまり、API の作成時には、コードを |
|
215 記述する前の設計の早い段階でドキュメンテーションコメントを記述し、 |
|
216 .B javadoc |
|
217 を実行できます。 |
|
218 .LP |
|
219 コンパイラに依存することによって、HTML 出力が、実際の実装に正確に対応 |
|
220 することが保証されます。実際の実装は、明示的でなく暗黙的に |
|
221 ソースコードに依存している場合があります。たとえば、 |
|
222 .B javadoc |
|
223 ツールは、 |
|
224 .B .class |
|
225 ファイル内には存在するが、ソースコード内には存在しない |
|
226 デフォルトコンストラクタ (「Java Language Specification」のセクション 8.6.7: http://java.sun.com/docs/books/jls/second_edition/html/names.doc.html#36154) |
|
227 をドキュメント化します。 |
|
228 .LP |
|
229 多くの場合、 |
|
230 .B javadoc |
|
231 ツールでは、ソースファイルのコードが不完全またはエラーを |
|
232 含んでいる場合でもドキュメントを生成できます。 |
|
233 このため、デバッグやトラブルシューティングが完了する前に |
|
234 ドキュメントを生成できます。 たとえば、Java 言語仕様によると、 |
|
235 抽象メソッドを含むクラスはそれ自体を抽象と宣言しなければなりません。 |
|
236 このエラーを検出すると、javac コンパイラの場合は、このエラーで |
|
237 停止しますが、javadoc ツールは警告を出さずに処理を進めます。 |
|
238 javadoc ツールはドキュメンテーションコメントの基本的なチェックを行います。 |
|
239 ドキュメンテーションコメントをより詳しくチェックする必要がある場合は、 |
|
240 DocCheck ドックレットを使用してください。 |
|
241 .LP |
|
242 .B javadoc |
|
243 ツールがドキュメント用の内部構造を構築するときは、参照する |
|
244 クラスをすべてロードします。このため、ブートストラップクラス、 |
|
245 拡張機能、またはユーザクラスにかかわらず、 |
|
246 .B javadoc |
|
247 ツールは、参照するクラスをすべて検出できなければなりません。 |
|
248 一般的に、作成する |
|
249 クラスは、拡張機能としてロードされるか、 |
|
250 .BR javadoc |
|
251 ツールのクラスパス内にある必要があります。 |
|
252 .SS "Javadoc ドックレット" |
|
253 .B javadoc |
|
254 ツールの出力の内容と形式は、ドックレットを使ってカスタマイズできます。 |
|
255 .B javadoc |
|
256 ツールには、標準ドックレットと呼ばれるデフォルトの「組み込み型」 |
|
257 ドックレットがあり、これによって HTML 形式の API |
|
258 ドキュメントを生成します。標準ドックレット |
|
259 の修正やサブクラス化を行なったり、HTML、XML、MIF、RTF などの好みの |
|
260 出力形式を生成する独自のドックレットを記述することも可能です。 |
|
261 ドックレットとその使用法については、次を参照してください。 |
|
262 .LP |
|
263 .TP 2 |
|
264 \(bu |
|
265 .B Javadoc |
|
266 ドックレット |
|
267 .TP 2 |
|
268 \(bu |
|
269 .B -doclet |
|
270 コマンド行オプション |
|
271 .LP |
|
272 .B -doclet |
|
273 コマンド行オプションでカスタムドックレットが指定されていない場合、 |
|
274 .B javadoc |
|
275 ツールは、デフォルトの標準ドックレットを使用します。 |
|
276 .B javadoc |
|
277 ツールには、どのドックレットが使われているかには関係なく使用できる |
|
278 コマンド行オプションがあります。標準ドックレットでは、これらの |
|
279 ほかに、いくつかのコマンド行オプションが追加されます。どちらの |
|
280 オプションについても、後述の「オプション」で説明します。 |
|
281 .SS 関連ドキュメントおよびドックレット |
|
282 .TP 2 |
|
283 \(bu |
|
284 Javadoc に施された機能強化 - Javadoc に追加された改良点の詳細 |
|
285 .TP 2 |
|
286 \(bu |
|
287 Javadoc FAQ - 頻繁に寄せられる質問に対する回答、Javadoc 関連のツールについての情報、およびバグの回避方法 |
|
288 .TP 2 |
|
289 \(bu |
|
290 Javadoc のドキュメンテーションを作成するには - Sun で |
|
291 一般的なドキュメンテーションコメントの記述方法の詳細 |
|
292 .TP 2 |
|
293 \(bu |
|
294 API 仕様を記述するための要件 - Java 2 プラットフォーム仕様を記述する際に |
|
295 使用された標準要件。 この情報は、ソースファイルのドキュメンテーションコメント |
|
296 形式で API 仕様を記述する場合にも、その他の形式で記述する場合にも |
|
297 役立ちます。 検証可能なアサーションを満たすパッケージ、クラス、 |
|
298 インタフェース、フィールド、およびメソッドについての要件を定めています。 |
|
299 .TP 2 |
|
300 \(bu |
|
301 ドキュメンテーションコメントの仕様 - ドキュメンテーションコメントの |
|
302 オリジナル仕様については、『Java Language Specification』 |
|
303 (James Gosling、Bill Joy、Guy Steele 共著) の初版の |
|
304 第 18 章「Documentation Comments」を参照してください。 |
|
305 この章は、第 2 版では削除されました。 |
|
306 .TP 2 |
|
307 \(bu |
|
308 DocCheck ドックレット - ソースファイル内のドキュメンテーションコメントを検査し、 |
|
309 見つかったエラーや不規則な箇所を一覧にしたレポートを生成します。 |
|
310 これは Sun Doc チェックユーティリティの一部です。 |
|
311 .TP 2 |
|
312 \(bu |
|
313 MIF ドックレット - MIF、FrameMaker、および PDF 形式での API ドキュメントの |
|
314 生成を自動化します。 MIF は Adobe FrameMaker の互換形式です。 |
|
315 .SS "用語" |
|
316 .LP |
|
317 .LP |
|
318 「\f2ドキュメンテーションコメント\fP」、「\f2doc コメント\fP」、「\f2主説明\fP」、「\f2タグ\fP」、「\f2ブロックタグ\fP」、および「\f2インラインタグ\fP」の用語については、「ドキュメンテーションコメント」で説明します。以下のその他の用語は、Javadoc ツールのコンテキストで特定の意味を持ちます。 |
|
319 .RS 3 |
|
320 .TP 3 |
|
321 生成されるドキュメント |
|
322 .B javadoc |
|
323 ツールが Java ソースコード内の doc コメントから生成したドキュメント |
|
324 のことです。デフォルトの生成ドキュメントは HTML 形式で、標準 |
|
325 ドックレットによって作成されます。 |
|
326 .LP |
|
327 .TP 3 |
|
328 名前 |
|
329 Java 言語での名前、つまりパッケージ、クラス、インタフェース、 |
|
330 フィールド、コンストラクタ、またはメソッドの名前のことです。名前は、 |
|
331 .BR java.lang.String.equals(java.lang.Object) |
|
332 のように完全修飾することも、 |
|
333 .BR equals(Object) |
|
334 のように部分修飾することもできます。 |
|
335 .LP |
|
336 .TP 3 |
|
337 ドキュメント化されるクラス |
|
338 .B javadoc |
|
339 の実行によって完全なドキュメントが生成されるクラスと |
|
340 インタフェースです。ドキュメント化するには、ソースファイルが |
|
341 使用可能でなければならず、ソースファイル名またはパッケージ名の |
|
342 どちらかを |
|
343 .B javadoc |
|
344 コマンドに渡さなければなりません。ドキュメント化されるクラスは、 |
|
345 .B javadoc |
|
346 の実行で組み込まれるクラス、つまり「組み込みクラス」とも呼ばれます。 |
|
347 .LP |
|
348 .TP 3 |
|
349 含まれるクラス |
|
350 対応するソースファイル名またはパッケージ名が javadoc コマンドに |
|
351 渡されるクラスおよびインタフェースのことです。 |
|
352 .LP |
|
353 .TP 3 |
|
354 除外されるクラス |
|
355 javadoc コマンドにソースファイル名またはパッケージ名が |
|
356 渡されないクラスとインタフェースです。 |
|
357 .LP |
|
358 .TP 3 |
|
359 参照クラス |
|
360 ドキュメント化されるクラスとインタフェースの定義 |
|
361 (実装) またはドキュメンテーションコメント内で明示的に参照される |
|
362 クラスとインタフェースです。参照の例としては、 |
|
363 戻り値の型、パラメータの型、キャストの型、 |
|
364 拡張されるクラス、実装されるインタフェース、 |
|
365 インポートされるクラス、メソッド本体で使用される |
|
366 クラス、@see、{@link}、{@linkplain}、 |
|
367 および {@inheritDoc} タグなどがあります |
|
368 (この定義は 1.3 |
|
369 .fi |
|
370 (http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses) |
|
371 から |
|
372 変更されていることに注意)。 |
|
373 javadoc ツールは動作中、 |
|
374 .B javadoc |
|
375 のブートクラスパスと |
|
376 クラスパス内にある参照されているクラスを |
|
377 すべてメモリにロードするためです。 |
|
378 参照されているクラスが見つからなかった |
|
379 場合は、[クラスが見つかりません] という警告が表示されます。 |
|
380 .B javadoc |
|
381 ツールは、クラスの存在とそのメンバの完全修飾名を決定するのに十分な情報を、 |
|
382 .B .class |
|
383 ファイルから引き出すことができます。 |
|
384 .LP |
|
385 .TP 3 |
|
386 外部参照クラス |
|
387 参照されるクラスのうち、 |
|
388 .B javadoc |
|
389 を実行してもドキュメントが生成されないクラスです。 |
|
390 つまり、これらのクラスは、コマンド行で |
|
391 .B javadoc |
|
392 ツールに渡されていません。 |
|
393 生成ドキュメント内でこれらのクラスにリンクしている箇所は、 |
|
394 「外部参照」または「外部リンク」と呼ばれます。 たとえば、 |
|
395 .B java.awt |
|
396 パッケージに対してだけ |
|
397 .B javadoc |
|
398 を実行した場合、Object などの |
|
399 .BR java.lang |
|
400 内のすべてのクラスは、外部参照クラスになります。外部参照クラスには、 |
|
401 .B \-link |
|
402 および |
|
403 .B \-linkoffline |
|
404 オプションを使ってリンクすることができます。 |
|
405 外部参照クラスには、通常そのソースコメントを |
|
406 .B \javadoc |
|
407 ツールの実行で利用できないという重要な特徴があります。 |
|
408 この場合、それらのコメントを継承することはできません。 |
|
409 .SH "ソースファイル" |
|
410 .B javadoc |
|
411 ツールは、クラスの Java 言語ソースファイル (\f3.java\f1)、パッケージコメントファイル、 |
|
412 概要コメントファイル、およびその他の処理されないファイルの 4 種類の |
|
413 「ソース」ファイルを基にして、出力を生成します。また、ドキュメント化しないがソースツリーに存在する場合があるテストファイルやテンプレートについても説明します。 |
|
414 .SS "クラスソースコードファイル" |
|
415 各クラスまたはインタフェース、およびそのメンバは、 |
|
416 .B .java |
|
417 ファイルの中にそれ自身のドキュメンテーションコメントを |
|
418 持つことができます。ドキュメンテーションコメントの詳細については、 |
|
419 「ドキュメンテーションコメント」の節を参照してください。 |
|
420 .SS "パッケージコメントファイル" |
|
421 各パッケージは、独自のドキュメンテーションコメントを |
|
422 持つことができ、「ソース」ファイルに保持します。 |
|
423 .B javadoc |
|
424 ツールは、生成するパッケージの要約ページにこのコメントをマージします。 |
|
425 通常、このコメントには、パッケージ全体に適用される |
|
426 ドキュメントを含めます。 |
|
427 .LP |
|
428 パッケージコメントファイルを作成する場合、コメントの格納先として、次の 2 つのファイルのいずれかを選択できます。 |
|
429 .LP |
|
430 .RS 3 |
|
431 .TP 2 |
|
432 o |
|
433 \f2package\-info.java\fP \- パッケージ宣言、パッケージ注釈、パッケージコメント、および Javadoc タグを格納できます。このファイルは JDK 5.0 で導入されたものであり、package.html よりも推奨されています。 |
|
434 .TP 2 |
|
435 o |
|
436 \f2package.html\fP \- 格納できるのはパッケージコメントと Javadoc タグだけです。パッケージ注釈は格納できません。 |
|
437 .RE |
|
438 |
|
439 .LP |
|
440 .LP |
|
441 各パッケージは、単一の \f2package.html\fP ファイル、単一の \f2package\-info.java\fP ファイルのいずれかを持つことができますが、両方を持つことはできません。このどちらかのファイルを \f2.java\fP ファイルとともに、ソースツリー内のそのパッケージのディレクトリ内に配置してください。 |
|
442 .LP |
|
443 .LP |
|
444 \f4package\-info.java\fP このファイルには、次の構造のパッケージコメントを格納できます。コメントはパッケージ宣言の前に配置します。 |
|
445 .LP |
|
446 .LP |
|
447 File: \f2java/applet/package\-info.java\fP |
|
448 .LP |
|
449 .ft 3 |
|
450 .nf |
|
451 /** |
|
452 * Provides the classes necessary to create an |
|
453 * applet and the classes an applet uses |
|
454 * to communicate with its applet context. |
|
455 * <p> |
|
456 * The applet framework involves two entities: |
|
457 * the applet and the applet context. |
|
458 * An applet is an embeddable window (see the |
|
459 * {@link java.awt.Panel} class) with a few extra |
|
460 * methods that the applet context can use to |
|
461 * initialize, start, and stop the applet. |
|
462 * |
|
463 * @since 1.0 |
|
464 * @see java.awt |
|
465 */ |
|
466 package java.lang.applet; |
|
467 .fi |
|
468 .ft 1 |
|
469 .LP |
|
470 コメント区切り文字の \f2/**\fP と \f2*/\fP は記述する必要がありますが、中間行の行頭のアスタリスクは省略してもかまいません。 |
|
471 .LP |
|
472 .LP |
|
473 \f4package.html\fP \- このファイルには、次の構造のパッケージコメントを格納できます。コメントは \f2<body>\fP 要素内に配置します。 |
|
474 .LP |
|
475 .LP |
|
476 File: \f2java/applet/package.html\fP |
|
477 .LP |
|
478 .LP |
|
479 .ft 3 |
|
480 .nf |
|
481 <HTML> |
|
482 <BODY> |
|
483 Provides the classes necessary to create an applet and the |
|
484 classes an applet uses to communicate with its applet context. |
|
485 <p> |
|
486 The applet framework involves two entities: the applet |
|
487 and the applet context. An applet is an embeddable |
|
488 window (see the {@link java.awt.Panel} class) with a |
|
489 few extra methods that the applet context can use to |
|
490 initialize, start, and stop the applet. |
|
491 |
|
492 @since 1.0 |
|
493 @see java.awt |
|
494 </BODY> |
|
495 </HTML> |
|
496 .fi |
|
497 .ft 1 |
|
498 .LP |
|
499 .LP |
|
500 これは単なる通常の HTML ファイルであり、パッケージ宣言を含んでいない点に注意してください。パッケージコメントファイルの内容は、ほかのすべてのコメントと同様に HTML で記述されています。ただし、ほかのコメントと異なる点が 1 つだけあります。それは、このドキュメンテーションコメントには、コメント区切り文字である \f2/**\fP と \f2*/\fP、および行頭のアスタリスクを含めてはならない、ということです。コメントを書く場合は、最初の文をパッケージの概要とし、\f2<body>\fP と最初の文の間にタイトルやその他のテキストを含めないようにします。パッケージタグを含めることはできますが、ほかのドキュメンテーションコメントと同様、全てのブロックタグは説明のあとに置かなければなりません。パッケージコメントファイルに \f2@see\fP タグを追加する場合は、完全指定の名前を使用する必要があります。詳細は、 |
|
501 .fi |
|
502 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#packagecomments |
|
503 の |
|
504 .na |
|
505 「\f2example of \fP\f2package.html\fP」を参照してください。 |
|
506 .LP |
|
507 .LP |
|
508 \f3パッケージコメントファイルの処理\fP \- Javadoc ツールは、実行時にパッケージコメントファイルを自動的に検索し、このファイルを見つけると次の処理を行います。 |
|
509 .LP |
|
510 .RS 3 |
|
511 .TP 2 |
|
512 o |
|
513 処理できるようにコメントをコピーする (\f2package.html\fP の場合であれば、\f2<body>\fP と \f2</body>\fP HTML タグの間にある内容をすべてコピーする。\f2<head>\fP を含め、そこに \f2<title>\fP やソースファイルの著作権記述などの情報を配置することもできるが、生成後のドキュメンテーションにはそれらは一切表示されない) |
|
514 .TP 2 |
|
515 o |
|
516 パッケージタグがあれば、すべて処理する |
|
517 .TP 2 |
|
518 o |
|
519 生成したパッケージの概要ページの最後に、処理したテキストを挿入する (例: パッケージの概要) |
|
520 .TP 2 |
|
521 o |
|
522 パッケージの概要ページの先頭に、パッケージコメントの最初の文をコピーする。さらに、概要ページのパッケージリストに、パッケージ名とパッケージコメントの最初の文を追加する (例: 概要の要約)。文の末尾は、クラスやメンバの主説明の最初の文の末尾と同じ規則によって判断される |
|
523 .RE |
|
524 |
|
525 .LP |
|
526 .SS "概要コメントファイル" |
|
527 ドキュメント化する各アプリケーションまたはパッケージのセットは、 |
|
528 独自の概要ドキュメンテーションコメントを持つことができ、それは |
|
529 「ソース」ファイルに保持されます。 |
|
530 .B javadoc |
|
531 ツールは、生成する概要ページにこのコメントをマージします。通常、この |
|
532 コメントには、アプリケーションまたはパッケージのセット全体に |
|
533 当てはまるドキュメントを含めます。 |
|
534 .LP |
|
535 概要コメントファイルを作成する場合、ファイルに好きな名前を付けて、 |
|
536 好きな場所に置くことができますが、通常はファイル名を |
|
537 .B overview.html |
|
538 にして、ソースツリーの一番上の階層に置きます。 |
|
539 たとえば、 |
|
540 .B java.applet |
|
541 パッケージのソースファイルが |
|
542 .B /home/user/src/java/applet |
|
543 ディレクトリに含まれているとすると、 |
|
544 .BR /home/user/src/overview.html |
|
545 に概要コメントファイルを作成することができます。 |
|
546 .LP |
|
547 異なるパッケージのセットに対して javadoc を複数回実行する場合は、同じ 1 つのソースファイルのセットに対して複数の概要コメントファイルを作成できます。 |
|
548 たとえば、内部ドキュメンテーション用に \-private を指定して javadoc を 1 回実行したあと、公開ドキュメンテーション用にそのオプションを指定しないで再度実行することができます。この場合、各概要コメントファイルの 1 文目で、そのドキュメンテーションを公開用または内部用として記述できます。 |
|
549 .LP |
|
550 概要コメントファイルの内容は、前に述べたパッケージコメントファイルと |
|
551 同様、HTML で記述された 1 つの大きなドキュメント |
|
552 コメントです。詳細は、前述の説明を参照してください。繰り返しに |
|
553 なりますが、このコメントを書く場合は、最初の文をアプリケーション |
|
554 またはパッケージのセットの要約にし、 |
|
555 .B <body> |
|
556 と最初の文の間にタイトルまたはその他のテキストを含めてはなりません。 |
|
557 概要タグを含めることができます。どのドキュメンテーションコメントに |
|
558 ついても、{\f3@link\f1} |
|
559 以外のタグは、説明のあとに置く必要があります。 |
|
560 .B @see |
|
561 タグを追加する場合は、完全指定の名前を使用する必要があります。 |
|
562 .LP |
|
563 .BR javadoc |
|
564 ツールの実行時に、 |
|
565 .B \-overview |
|
566 オプションを使って概要コメントファイル名を指定します。ファイルは、 |
|
567 パッケージコメントファイルと同じように処理されます。 |
|
568 .TP 2 |
|
569 \(bu |
|
570 .B <body> |
|
571 タグと |
|
572 .B </body> |
|
573 タグとの間にあるすべての内容を処理のためにコピーする |
|
574 .TP 2 |
|
575 \(bu |
|
576 存在する概要タグを処理する |
|
577 .TP 2 |
|
578 \(bu |
|
579 概要の要約などの Javadoc が生成する概要ページの最後に、 |
|
580 処理されたテキストを挿入する |
|
581 .TP 2 |
|
582 \(bu |
|
583 概要ページの先頭に、概要コメントの最初の文をコピーする |
|
584 .SS "その他の処理されないファイル" |
|
585 ソースには、 |
|
586 .B javadoc |
|
587 ツールで生成先のディレクトリにコピーする、その他の任意のファイルを |
|
588 含めることができます。一般に、このようなファイルには、 |
|
589 サンプルのグラフィックファイル、Java ソース |
|
590 (\f3.java\f1) およびクラス (\f3.class\f1) ファイル、内容が |
|
591 通常の Java ソース |
|
592 ファイルのドキュメンテーションコメントの影響を受けない |
|
593 独立した HTML ファイルなどがあります。 |
|
594 .LP |
|
595 処理されないファイルを含めるには、それらのファイルを |
|
596 .BR doc-files |
|
597 というディレクトリに置きます。このディレクトリは、任意のパッケージ |
|
598 ディレクトリの下に作成できます。パッケージごとにこのようなサブ |
|
599 ディレクトリを 1 つ持つことができます。このサブディレクトリには、 |
|
600 イメージ、サンプルコード、ソースファイル、 |
|
601 .B .class |
|
602 ファイル、アプレット、および HTML ファイルを入れることができます。 |
|
603 たとえば、ボタンの画像 |
|
604 .B button.gif |
|
605 を |
|
606 .B java.awt.Button |
|
607 クラスドキュメントに含めたい場合は、そのファイルを |
|
608 .B /home/user/src/java/awt/doc-files/ |
|
609 ディレクトリに置きます。 |
|
610 .BR doc-files |
|
611 ディレクトリを |
|
612 .B /home/user/src/java/doc-files |
|
613 に置くことはできません。これは、 |
|
614 .B java |
|
615 はパッケージではなく、そのディレクトリそのものにソースファイルが |
|
616 入っていないからです。 |
|
617 .LP |
|
618 これらの処理されないファイルへのリンクは |
|
619 すべて明示的に記述する必要があります。これは、 |
|
620 .B javadoc |
|
621 ツールがファイルを見ずに、単にディレクトリとその内容物を生成先に |
|
622 コピーするだけだからです。たとえば、 |
|
623 .B Button.java |
|
624 ドキュメンテーションコメント内のリンクは、次のようになります。 |
|
625 .LP |
|
626 .ft 3 |
|
627 .nf |
|
628 /** |
|
629 * This button looks like this: |
|
630 * <img src="doc-files/Button.gif"> |
|
631 */ |
|
632 .fi |
|
633 .ft 1 |
|
634 .SH "テストファイルおよびテンプレートファイル" |
|
635 一部の開発者から、テストファイルおよびテンプレートファイルを |
|
636 対応するソースファイルの近くのソースツリーに保存したいという要望がありました。 |
|
637 つまり、これらのソースファイルと同じディレクトリまたはサブディレクトリに |
|
638 保存したいということです。 |
|
639 .LP |
|
640 個別のソースファイル名で明示的に渡して |
|
641 .B Javadoc |
|
642 ツールを実行する場合は、 |
|
643 テストファイルおよびテンプレートファイルを意図的に除外して、 |
|
644 処理されないようにすることができます。ただし、パッケージ名または |
|
645 ワイルドカードで渡す場合は、以下のルールに従って、これらのテストファイル |
|
646 およびテンプレートファイルが |
|
647 処理されないようにする必要があります。 |
|
648 .LP |
|
649 テストファイルとテンプレートファイルの違いは、 |
|
650 テストファイルは、正当でコンパイル可能なソースファイルであるのに対して、 |
|
651 テンプレートファイルは、そうではないという点です。ただし、 |
|
652 テンプレートファイルも「.java」で終わることができます。 |
|
653 .TP |
|
654 テストファイル \- |
|
655 開発者の多くは、あるパッケージのコンパイル可能で実行可能な |
|
656 テストファイルをそのパッケージのソースファイルと同じ |
|
657 ディレクトリに配置したいと考えています。 |
|
658 しかしテストファイルは、名前なしパッケージなど、 |
|
659 ソースファイルパッケージとは別のパッケージに属させたいとも |
|
660 考えています (そのため、テストファイルには package ステートメントがないか、 |
|
661 またはソースとは別の package ステートメントがあります)。 |
|
662 このような状況では、コマンド行で指定されているソースのパッケージ名を指定して |
|
663 そのソースがドキュメント化されているときに、 |
|
664 テストファイルは警告またはエラーを引き起こします。 |
|
665 そのようなテストファイルはサブディレクトリに配置する必要があります。 |
|
666 たとえばソースファイルのテストファイルを |
|
667 .B com.package1 |
|
668 に追加する場合は、それらのテストファイルを、ハイフンが含まれるため |
|
669 パッケージ名としては無効になる |
|
670 サブディレクトリに配置します。 |
|
671 .LP |
|
672 .RS 5 |
|
673 com/package1/test-files/ |
|
674 .RE |
|
675 .LP |
|
676 こうすると、 |
|
677 .B Javadoc |
|
678 ツールでは警告なしで |
|
679 test ディレクトリをスキップします。 |
|
680 .LP |
|
681 テストファイルに doc コメントが含まれる場合、 |
|
682 次のようにワイルドカードを含んだテストソースファイル名で渡して |
|
683 テストファイルのドキュメントを生成するように、 |
|
684 .B Javadoc |
|
685 ツールを別個に実行できるように設定できます。 |
|
686 \f2com/package1/test\-files/*.java\fP. |
|
687 .TP |
|
688 ソースファイルのテンプレート\- |
|
689 テンプレートファイルの名前は「.java」で終わることもありますが、 |
|
690 テンプレートファイルはコンパイルできません。 |
|
691 ソースディレクトリに保持したいソースファイルの |
|
692 テンプレートがある場合は、 |
|
693 このファイル名にハイフン (Buffer-Template.java など) や |
|
694 その他の不正な Java 文字を使用します。 |
|
695 こうすることで、処理されないようになります。 |
|
696 これは、 |
|
697 .B Javadoc |
|
698 ツールが処理するのは、「.java」接尾辞を除いた名前が |
|
699 正規のクラス名であるソースファイルだけであるためです (「識別子」http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#40625 参照)。 |
|
700 .SS "生成されるファイル" |
|
701 デフォルトでは、 |
|
702 .B javadoc |
|
703 は、HTML 形式のドキュメントを生成する標準ドックレットを |
|
704 使います。 |
|
705 このドックレットは、以下の種類のファイルを生成します。以下の |
|
706 各 HTML「ページ」は、それぞれ別のファイルに対応します。 |
|
707 .B javadoc |
|
708 が生成するファイルの名前には、クラスやインタフェースの名前に |
|
709 ちなんだものと、そうでないもの (\f3package-summary.html\f1 など) |
|
710 の 2 種類があります。後者のグループには、前者のグループの名前と |
|
711 ファイル名が競合しないように、ハイフンが含まれています。 |
|
712 .SS "基本内容ページ" |
|
713 .TP 2 |
|
714 \(bu |
|
715 ドキュメント化する各クラスまたは各インタフェースに対し、1 つのクラス |
|
716 ページまたはインタフェースページ (\f3classname.html\f1) |
|
717 .TP 2 |
|
718 \(bu |
|
719 ドキュメント化する各パッケージに対し、1 つのパッケージ |
|
720 ページ (\f3package-summary.html\f1)。 |
|
721 .B javadoc |
|
722 ツールによって、ソースツリーのパッケージディレクトリ内の |
|
723 .B package.html |
|
724 または |
|
725 package\-info.java |
|
726 というファイル内のすべての HTML テキストが含められる |
|
727 .TP 2 |
|
728 \(bu |
|
729 パッケージのセット全体に対して 1 つの概要 |
|
730 ページ (\f3overview-summary.html\f1)。これは、生成される |
|
731 ドキュメントの先頭ページになる。 |
|
732 .B javadoc |
|
733 ツールによって、 |
|
734 .B -overview |
|
735 オプションで指定されたファイル内のすべての HTML テキストが含められる。 |
|
736 このファイルが作成されるのは、 |
|
737 .B javadoc |
|
738 に 2 つ以上のパッケージ名を渡した |
|
739 場合だけであることに注意する。詳細は、以下の「HTML フレーム」節を参照 |
|
740 .SS "相互参照ページ" |
|
741 .TP 2 |
|
742 \(bu |
|
743 パッケージのセット全体に対して 1 つのクラス階層ページ |
|
744 (\f3overview-tree.html\f1)。これを表示するには、ナビゲーション |
|
745 バーの [概要] をクリックしてから、[階層ツリー] をクリックする |
|
746 .TP 2 |
|
747 \(bu |
|
748 各パッケージに対して 1 つのクラス階層 |
|
749 ページ (\f3package-tree.html\f1)。 |
|
750 特定のパッケージページ、クラスページ、またはインタフェースページを |
|
751 表示し、[階層ツリー] をクリックすると、そのパッケージの階層が |
|
752 表示される |
|
753 .TP 2 |
|
754 \(bu |
|
755 各パッケージに対して 1 つの [使用] |
|
756 ページ (\f3package-use.html\f1)と、 |
|
757 各クラスおよびインタフェースに対して別に 1 つの [使用] |
|
758 ページ(\f3class-use/classname.html\f1)。このページは、特定のクラス、 |
|
759 インタフェース、またはパッケージのなんらかの部分を使っている |
|
760 パッケージ、クラス、メソッド、コンストラクタ、およびフィールドを |
|
761 記述する。クラスまたはインタフェース A について考えると、 |
|
762 その[使用] ページには、A のサブクラス、A として宣言された |
|
763 フィールド、A を返すメソッド、A 型のパラメータを持つメソッド |
|
764 およびコンストラクタが表示される。このページには、パッケージ、 |
|
765 クラス、またはインタフェースに移動してから、ナビゲーションバー |
|
766 の [使用] リンクをクリックすることによってアクセスできる |
|
767 .TP 2 |
|
768 \(bu |
|
769 非推奨 API ページ (\f3deprecated-list.html\f1)。推奨されない |
|
770 名前すべての一覧が含まれている (非推奨名は、通常は改良された API が |
|
771 存在するために使用が推奨されていない API の名前で、たいていはそれに |
|
772 置き換わる名前が提示されている。非推奨 API は、将来の実装では |
|
773 削除される可能性がある) |
|
774 .TP 2 |
|
775 \(bu |
|
776 定数フィールド値ページ (\f3constant-values.html\f1) 。 |
|
777 static フィールドの値が表示される。 |
|
778 .TP 2 |
|
779 \(bu |
|
780 直列化形式ページ (\f3serialized-form.html\f1)。直列化可能クラス |
|
781 および外部化可能クラスの情報用。これらの各クラスには、直列化 |
|
782 フィールドおよびメソッドに関する説明がある。これらの情報は、API を |
|
783 使う開発者ではなく、再実装者に必要な情報である。ナビゲーションバーに |
|
784 リンクがない場合、任意の直列化されたクラスに移動して、 |
|
785 クラスの [関連項目] セクション内の [直列化された形式] をクリック |
|
786 するとこの情報を取得できる |
|
787 標準ドックレットは、直列化された形式のページを自動的に生成する。 |
|
788 ここには、Serializable を実装する public または非 public の |
|
789 クラスが組み込まれており、さらに、 |
|
790 .B readObject |
|
791 メソッド、 |
|
792 .B writeObject |
|
793 メソッド、直列化されたフィールド、 |
|
794 および @serial タグ、@serialField タグ、@serialData タグからの |
|
795 ドキュメンテーションコメントが組み込まれている。 |
|
796 直列化が可能な public クラスを除外するには、 |
|
797 そのクラスまたはそのクラスが属するパッケージを @serial exclude タグで |
|
798 指定する。直列化が可能な package private クラスを含めるには、 |
|
799 そのクラスまたはそのクラスが属するパッケージを @serial include タグで |
|
800 指定する。 1.4 では、 |
|
801 \-private |
|
802 オプションを指定せずに javadoc を実行することで、public クラスおよび |
|
803 private クラスに完全な直列化形式を生成することができる。 |
|
804 .TP 2 |
|
805 \(bu |
|
806 索引 (\f3index-*.html\f1)。すべてのクラス名、 |
|
807 インタフェース名、コンストラクタ名、フィールド名、およびメソッド名を |
|
808 アルファベット順に並べてある。索引は、Unicode を扱えるように |
|
809 国際化されており、1 つのファイルとして生成するか、または先頭 |
|
810 文字 (英語の場合 A から Z) ごとに別のファイルとして生成できる |
|
811 .SS "サポートファイル" |
|
812 .TP 2 |
|
813 \(bu |
|
814 ヘルプページ (\f3help-doc.html\f1)。ナビゲーションバーおよび |
|
815 上記のページについて説明する。 |
|
816 .BR \-helpfile |
|
817 を使って、デフォルトの |
|
818 ヘルプファイルに置き換わる独自のカスタムヘルプファイルを提供する |
|
819 こともできる |
|
820 .TP 2 |
|
821 \(bu |
|
822 1 つの |
|
823 .B index.html |
|
824 ファイル。表示用 の HTML フレームを作成する。このファイルは、 |
|
825 フレーム付きの最初のページを表示する場合にロードする。このファイル |
|
826 自体は、テキスト内容を含まない |
|
827 .TP 2 |
|
828 \(bu |
|
829 複数のフレームファイル (\f3*-frame.html\f1)。パッケージ、クラス、 |
|
830 およびインタフェースの一覧を含む。HTML フレームを表示するときに |
|
831 使われる |
|
832 .TP 2 |
|
833 \(bu |
|
834 パッケージリストファイル (\f3package-list\f1)。 |
|
835 .B \-link |
|
836 オプションおよび |
|
837 .B \-linkoffline |
|
838 オプションで使われる。これは、HTML ファイルではなくテキストファイル |
|
839 のため、リンクではアクセスできない |
|
840 .TP 2 |
|
841 \(bu |
|
842 スタイルシートファイル (\f3stylesheet.css\f1)。生成されるページ上に |
|
843 表示される限られた色数、フォントファミリ、フォントサイズ、フォントの |
|
844 スタイルおよび配置を制御する |
|
845 .TP 2 |
|
846 \(bu |
|
847 コピー先ディレクトリにコピーしたいファイル (イメージ、サンプル、 |
|
848 ソースファイルなど) が入っている doc ファイルのディレクトリ。 |
|
849 .B javadoc |
|
850 ツールはこのようなファイルを処理しない。つまり、このようなファイル内の |
|
851 .B javadoc |
|
852 タグはすべて無視される。ソースツリーに存在しない限り、この |
|
853 ディレクトリは生成されない |
|
854 .SS "HTML フレーム" |
|
855 .B javadoc |
|
856 ツールは、下の図に示すように、2 つか 3 つの HTML フレームを生成します。 |
|
857 1 つのパッケージしかない場合 (またはパッケージがない場合) は、パッケージの一覧を省略することによって最低限必要な数のフレームを作成します。 |
|
858 ソースファイル (*\f3.java\f1) または単一のパッケージ名を引数として |
|
859 .B javadoc |
|
860 コマンドに渡す場合は、左側の列にクラスの一覧を表示する |
|
861 フレーム (C) 1 つだけが作成されます。 |
|
862 .B javadoc |
|
863 に複数のパッケージ名を渡す場合は、概要ページ (Detail) に加えて、 |
|
864 すべてのパッケージの一覧を表示する第 3 のフレーム (P) が |
|
865 作成されます。この概要ページのファイル名は |
|
866 .BR overview-summary.html |
|
867 です。したがって、このファイルが作成されるのは、2 つ以上のパッケージ |
|
868 名を渡した場合だけです。[フレームなし] リンクをクリックするか、 |
|
869 .BR overview-summary.html |
|
870 から表示するようにすると、フレームを省略できます。 |
|
871 .LP |
|
872 HTML フレームに慣れていない場合は、フレームには、印刷および |
|
873 スクロール用の「フォーカス」が必要であることに注意する |
|
874 必要があります。フレームにフォーカスを与えるには、そのフレームを |
|
875 クリックします。すると、多くのブラウザでは、矢印キーおよびページキー |
|
876 を使ってそのフレームをスクロールしたり、[印刷] メニュー |
|
877 コマンドを使ってそのフレームを印刷したりできるようになります。 |
|
878 .LP |
|
879 .ft 3 |
|
880 .nf |
|
881 ------------ ------------ |
|
882 |C| Detail | |P| Detail | |
|
883 | | | | | | |
|
884 | | | |-| | |
|
885 | | | |C| | |
|
886 | | | | | | |
|
887 | | | | | | |
|
888 ------------ ------------ |
|
889 javadoc *.java javadoc java.lang java.awt |
|
890 .fi |
|
891 .ft 1 |
|
892 .LP |
|
893 HTML フレームが必要かどうかによって、次のどちらかのファイルを |
|
894 開始ページとしてロードします。 |
|
895 .LP |
|
896 .TP 2 |
|
897 \(bu |
|
898 .B index.html |
|
899 (フレームあり) |
|
900 .TP 2 |
|
901 \(bu |
|
902 .B overview-summary.html |
|
903 (フレームなし) |
|
904 .SS "生成されるファイル構造" |
|
905 生成されるクラスファイルおよびインタフェースファイルは、Java ソース |
|
906 ファイルおよびクラスファイルと同じディレクトリ階層で組織 |
|
907 されます。この構造は、1 つのサブパッケージにつき 1 つのディレクトリ |
|
908 で構成されます。 |
|
909 .LP |
|
910 たとえば、 |
|
911 .B java.applet.Applet |
|
912 クラスに対して生成されるドキュメントは、 |
|
913 .BR java/applet/Applet.html |
|
914 に格納されます。生成先のディレクトリの名前が apidocs だと |
|
915 すると、java.applet パッケージのファイル構造もこれに従います。 |
|
916 前述したように、「frame」という語を名前に含むファイルは、 |
|
917 すべて左上または左下のフレームに表示されます。それ |
|
918 以外の HTML ファイルは、すべて右側のフレームに表示されます。 |
|
919 .LP |
|
920 注: ディレクトリは、太字 (bold) で示してあります。 |
|
921 アスタリスク (*) は、 |
|
922 .B javadoc |
|
923 への引数がパッケージ名でなくソースファイル名 (*\f3.java\f1) の |
|
924 ときに、省略されるファイルおよびディレクトリを示しています。また、 |
|
925 引数がソースファイル名のときには、 |
|
926 .B package-list |
|
927 は作成されますが、空です。 |
|
928 .B doc-files |
|
929 ディレクトリは、ソースツリー内に存在しない限り、生成先に表示されません。 |
|
930 .LP |
|
931 .RE |
|
932 .nf |
|
933 \f3 |
|
934 .fl |
|
935 |
|
936 .fl |
|
937 \fP\f3apidocs\fP 最上位ディレクトリ |
|
938 .fl |
|
939 index.html HTML フレームを設定する初期ページ |
|
940 .fl |
|
941 * overview\-summary.html 全パッケージのリスト。先頭に要約文がある |
|
942 .fl |
|
943 overview\-tree.html 全パッケージのクラス階層のリスト |
|
944 .fl |
|
945 deprecated\-list.html 全パッケージの推奨されない API のリスト |
|
946 .fl |
|
947 constant\-values.html 全パッケージの static フィールドの値のリスト |
|
948 .fl |
|
949 serialized\-form.html 全パッケージの直列化された形式のリスト |
|
950 .fl |
|
951 * overview\-frame.html 全パッケージのリスト。左上のフレームに表示される |
|
952 .fl |
|
953 allclasses\-frame.html 全パッケージの全クラスのリスト。左下のフレームに表示される |
|
954 .fl |
|
955 help\-doc.html これらのページの構成を示すユーザヘルプを表示する |
|
956 .fl |
|
957 index\-all.html \-splitindex オプションなしで作成されたデフォルト索引 |
|
958 .fl |
|
959 \f3index\-files\fP \-splitindex オプションを指定して作成されたディレクトリ |
|
960 .fl |
|
961 index\-<number>.html \-splitindex オプションを指定して作成された索引ファイル |
|
962 .fl |
|
963 package\-list パッケージ名のリスト。外部参照を解決するためだけに使用される |
|
964 .fl |
|
965 stylesheet.css フォント、色、配置を定義する HTML スタイルシート |
|
966 .fl |
|
967 \f3java\fP パッケージディレクトリ |
|
968 .fl |
|
969 \f3applet\fP サブパッケージディレクトリ |
|
970 .fl |
|
971 Applet.html Applet クラスのページ |
|
972 .fl |
|
973 AppletContext.html AppletContext インタフェースのページ |
|
974 .fl |
|
975 AppletStub.html AppletStub インタフェースのページ |
|
976 .fl |
|
977 AudioClip.html AudioClip インタフェースのページ |
|
978 .fl |
|
979 * package\-summary.html このパッケージのクラスのリスト。先頭に要約文がある |
|
980 .fl |
|
981 * package\-frame.html このパッケージのクラスのリスト。左下のフレームに表示される |
|
982 .fl |
|
983 * package\-tree.html このパッケージのクラス階層のリスト |
|
984 .fl |
|
985 package\-use このパッケージが使用されている場所のリスト |
|
986 .fl |
|
987 \f3doc\-files\fP イメージやサンプルのファイルが格納されるディレクトリ |
|
988 .fl |
|
989 \f3class\-use\fP API が使用されている場所のページを格納するディレクトリ |
|
990 .fl |
|
991 Applet.html Applet クラスを使用するページ |
|
992 .fl |
|
993 AppletContext.html AppletContext インタフェースを使用するページ |
|
994 .fl |
|
995 AppletStub.html AppletStub インタフェースを使用するページ |
|
996 .fl |
|
997 AudioClip.html AudioClip インタフェースを使用するページ |
|
998 .fl |
|
999 \f3src\-html\fP ソースコードディレクトリ |
|
1000 .fl |
|
1001 \f3java\fP パッケージディレクトリ |
|
1002 .fl |
|
1003 \f3applet\fP サブパッケージディレクトリ |
|
1004 .fl |
|
1005 Applet.html Applet ソースコードのページ |
|
1006 .fl |
|
1007 AppletContext.html AppletContext ソースコードのページ |
|
1008 .fl |
|
1009 AppletStub.html AppletStub ソースコードのページ |
|
1010 .fl |
|
1011 AudioClip.html AudioClip ソースコードのページ |
|
1012 .fl |
|
1013 .fi |
|
1014 |
|
1015 .LP |
|
1016 .SS "生成される API 宣言" |
|
1017 javadoc ツールは、各クラス、インタフェース、フィールド、コンストラクタ、 |
|
1018 およびメソッドの説明の初めで宣言を生成します。 |
|
1019 この宣言は、その API 項目の宣言です。たとえば、 |
|
1020 ブール型クラスの宣言は次のようになります。 |
|
1021 .LP |
|
1022 .LP |
|
1023 \f2public final class Boolean\fP |
|
1024 .br |
|
1025 \f2extends Object\fP |
|
1026 .br |
|
1027 \f2implements Serializable\fP |
|
1028 .LP |
|
1029 .LP |
|
1030 Boolean.valueOf メソッドの宣言は次のようになります。 |
|
1031 .LP |
|
1032 .LP |
|
1033 \f2public static Boolean valueOf(String s)\fP |
|
1034 .LP |
|
1035 .LP |
|
1036 javadoc ツールは修飾子 |
|
1037 .BR public |
|
1038 、 |
|
1039 .BR protected |
|
1040 、 |
|
1041 .BR private |
|
1042 、 |
|
1043 .BR abstract |
|
1044 、 |
|
1045 .BR final |
|
1046 、 |
|
1047 .BR static |
|
1048 、 |
|
1049 .BR transient |
|
1050 、 |
|
1051 および |
|
1052 .BR volatile |
|
1053 を組み込むことができますが、 |
|
1054 .BR synchronized |
|
1055 と |
|
1056 .BR native |
|
1057 は組み込むことができません。 |
|
1058 .BR synchronized |
|
1059 と |
|
1060 .BR native |
|
1061 修飾子は実装の詳細と見なされ、API 仕様の一部とは見なされません。 |
|
1062 .LP |
|
1063 キーワード |
|
1064 .BR synchronized |
|
1065 に依存するよりも、「複数のスレッドによって単一の |
|
1066 .BR Enumeration |
|
1067 を並行して使用してはならない」というように、並行処理のセマンティックスを |
|
1068 コメント説明の中でドキュメント化するべきです。ドキュメントでは、 |
|
1069 これらのセマンティックスの達成方法を説明すべきではありません。別の |
|
1070 例を挙げると、 |
|
1071 .BR Hashtable |
|
1072 はスレッドに対して安全でなければなりませんが、エクスポートされるその |
|
1073 メソッドすべてを同期させることによってこれを実現すると明記する必要 |
|
1074 はないということです。バケットレベルで内部的に同期をとる権限を留保して、 |
|
1075 より高度な並行性を提供すべきです。 |
|
1076 .LP |
|
1077 .SH "ドキュメンテーションコメント" |
|
1078 .LP |
|
1079 .LP |
|
1080 オリジナルの「ドキュメンテーションコメントの仕様」は、「関連項目」を参照してください。 |
|
1081 .LP |
|
1082 .SS |
|
1083 ソースコードへのコメントの挿入 |
|
1084 .LP |
|
1085 .LP |
|
1086 ソースコードの任意の宣言 (クラス、インタフェース、メソッド、コンストラクタ、 |
|
1087 またはフィールド) の前に、ドキュメンテーションコメント (doc コメント) |
|
1088 を記述することができます。 各パッケージにドキュメンテーションコメントを |
|
1089 作成でき、構文は若干異なりますが、概要にもドキュメンテーションコメントを |
|
1090 作成できます。 ドキュメンテーションコメントは、Javadoc コメントとも呼ばれます。 |
|
1091 ドキュメンテーションコメントは、コメントの始まりを示す文字列 |
|
1092 .B /** |
|
1093 と、コメントの終わりを示す文字列 |
|
1094 .B */ |
|
1095 の間にある文字で構成されます。 行頭のアスタリスクは、各行に記述できます。詳細は、以下で説明します。 Linux ではテキストは、複数行にわたって記述できます。 |
|
1096 .LP |
|
1097 .RS |
|
1098 .ft 3 |
|
1099 .nf |
|
1100 /** |
|
1101 * This is the typical format of a simple documentation comment |
|
1102 * that spans two lines. |
|
1103 */ |
|
1104 .fi |
|
1105 .ft 1 |
|
1106 .RE |
|
1107 .LP |
|
1108 次のように、コメントは 1 行にまとめることもできます。 |
|
1109 .LP |
|
1110 .RS |
|
1111 .ft 3 |
|
1112 .nf |
|
1113 /** This comment takes up only one line. */ |
|
1114 .fi |
|
1115 .ft 1 |
|
1116 .RE |
|
1117 .LP |
|
1118 コメントの配置 - ドキュメンテーションコメントが認識されるのは、クラス、 |
|
1119 インタフェース、コンストラクタ、メソッド、またはフィールド |
|
1120 宣言の前に置かれた場合だけです (クラス、メソッド、およびフィールドの |
|
1121 例を参照)。メソッドの本体に置かれたドキュメント |
|
1122 コメントは無視されます。 |
|
1123 .B javadoc |
|
1124 ツールは、宣言文ごとに 1 つのドキュメンテーションコメントだけを |
|
1125 認識します。 |
|
1126 .LP |
|
1127 よく発生する間違いは、重要な文をクラスコメントとクラス宣言の間に |
|
1128 入れてしまうことです。 |
|
1129 .B javadoc |
|
1130 はクラスコメントを無視するため、注意してください。 |
|
1131 .LP |
|
1132 .RS |
|
1133 .ft 3 |
|
1134 .nf |
|
1135 /** |
|
1136 * This is the class comment for the class Whatever. |
|
1137 */ |
|
1138 |
|
1139 import com.sun; // MISTAKE - Important not to put statements here |
|
1140 |
|
1141 public class Whatever { |
|
1142 } |
|
1143 .fi |
|
1144 .ft 1 |
|
1145 .RE |
|
1146 .LP |
|
1147 コメントの説明のあとにタグが続く - コメントの開始区切り文字である |
|
1148 .B /** |
|
1149 のあとからタグセクションまでが説明になります。 タグセクションは、 |
|
1150 先頭文字が |
|
1151 .B @ |
|
1152 である行から始まります (行の先頭のアスタリスクおよび空白文字 |
|
1153 は除く)。 説明を記述せず、コメントだけのタグを記述することもできます。 |
|
1154 説明は、タグセクション以降に続けることはできません。 |
|
1155 タグの引数は複数の行にまたがって記述できます。 タグの数に |
|
1156 制限はありません。何回も記述できるタグと、1 回しか記述できない |
|
1157 タグがあります。 次の例の |
|
1158 .B @see |
|
1159 からタグセクションが始まります。 |
|
1160 .LP |
|
1161 .nf |
|
1162 \f3 |
|
1163 .fl |
|
1164 /** |
|
1165 .fl |
|
1166 * This sentence would hold the main description for this doc comment. |
|
1167 .fl |
|
1168 * @see java.lang.Object |
|
1169 .fl |
|
1170 */ |
|
1171 .fl |
|
1172 \fP |
|
1173 .fi |
|
1174 |
|
1175 .LP |
|
1176 .LP |
|
1177 標準タグとインラインタグ: タグは、javadoc ツールが処理できる、 |
|
1178 doc コメント内の特別なキーワードです。javadoc ツールには、@tag として現れる |
|
1179 標準タグと、中括弧内に |
|
1180 .B {\f3@tag\f1} |
|
1181 として現れるインラインタグがあります。解釈 |
|
1182 させるためには、先頭のアスタリスク、空白、コメント区切り文字 (/**) を |
|
1183 除いては標準タグが行の先頭であるように配置する必要があります。つ |
|
1184 まり、ユーザはテキスト内の任意の位置で @ 文字を使用でき、 |
|
1185 この文字はタグの始めとは解釈されません。@ 文字で行を開 |
|
1186 始してこれが解釈されないようにしたい場合は、HTML エンティティの |
|
1187 @ を使用してください。各スタンドアロンタグには関連するテキストがあり |
|
1188 ます。これは、そのタグの後から次のタグの直前まで、または doc コメント |
|
1189 の最後までの任意のテキストです。関連付けられたテキストは、 |
|
1190 複数行にまたがって記述できます。 |
|
1191 インラインタグは、そのテキストが許 |
|
1192 可される位置にはどこでも指定でき、解釈の対象となります。次の例は、 |
|
1193 標準タグ |
|
1194 .BR @deprecated |
|
1195 とインラインタグ |
|
1196 .BR {@link} |
|
1197 が含まれています。 |
|
1198 .LP |
|
1199 .RS |
|
1200 .ft 3 |
|
1201 .nf |
|
1202 /** |
|
1203 * @deprecated As of JDk 1.1, replaced by {@link #setBounds(int,int,int,int)} |
|
1204 */ |
|
1205 .fi |
|
1206 .ft 1 |
|
1207 .RE |
|
1208 .LP |
|
1209 コメントは HTML で記述します。テキストは HTML で |
|
1210 記述しなければなりません。 |
|
1211 これは、HTML のエンティティを使う必要があること、 |
|
1212 および HTML タグを使用できること |
|
1213 を意味します。HTML は、使用するブラウザがサポートする |
|
1214 任意のバージョンを使うことが |
|
1215 できます。標準ドックレットは、階層式スタイルシートと |
|
1216 フレームを含むほかの部分 (ドキュメンテーションコメント |
|
1217 以外) は、HTML 3.2 に準拠したコードを生成するように記述 |
|
1218 されています |
|
1219 (フレームセット対応のため、生成される各 |
|
1220 ファイルは、「HTML 4.0」で始まる)。 |
|
1221 .LP |
|
1222 たとえば、より小さい (<) およびより大きい (>) という |
|
1223 記号は、 |
|
1224 .B < |
|
1225 と |
|
1226 .BR > |
|
1227 と記述する必要があります。同様に、アンパサンド (&) は、 |
|
1228 .BR & |
|
1229 と記述する必要があります。次の例で |
|
1230 は、ボールドの HTML タグ <b> を示します。 |
|
1231 .LP |
|
1232 次に doc コメントを示します。 |
|
1233 .LP |
|
1234 .RS |
|
1235 .ft 3 |
|
1236 .nf |
|
1237 /** |
|
1238 * This is a <b>doc</b> comment. |
|
1239 * @see java.lang.Object |
|
1240 */ |
|
1241 .fi |
|
1242 .ft 1 |
|
1243 .RE |
|
1244 .LP |
|
1245 行頭のアスタリスク - |
|
1246 .B javadoc |
|
1247 は、doc コメントを解析するときに、各行の先頭にある |
|
1248 文字アスタリスク (*) をすべて破棄し |
|
1249 ます。また、最初のアスタリスク (*) より前の空白と |
|
1250 タブも破棄します。1.4 からは、行頭のアスタリスクを省略した場合、行頭の空白は削除されません。これにより、<PRE> タグの中の doc コメントに、サンプルコードをインデントを残したままで直接ペーストすることができます。空白は一般的に、タブよりも均一にブラウザで解釈されます。インデントは、区切り文字 /** や <PRE> タグではなく、左マージンに相対的です。 |
|
1251 .LP |
|
1252 最初の文 - 各 doc コメントの最初の文は、宣言されている |
|
1253 エンティティに関する簡潔かつ完全 |
|
1254 な説明を含む要約文でなければなりません。 |
|
1255 この文は、空白、タブ、または行末記 |
|
1256 号が続いている最初のピリオド、あるいは最初のスタンドアロンタグで終了します。 |
|
1257 .B javadoc |
|
1258 ツールは、HTML ページの最初にあるメンバ要約に、この最初の文をコピーします。 |
|
1259 .LP |
|
1260 複数フィールドの宣言 - |
|
1261 .B java |
|
1262 では、単一の文で複数のフィールドを宣言できます。 |
|
1263 しかし、この文のドキュメンテ |
|
1264 ーションコメントは 1 つだけで、このコメントが |
|
1265 すべてのフィールドにコピーされます。 |
|
1266 したがって、フィールドごとに個々の |
|
1267 ドキュメンテーションコメントを付けたい場合は、 |
|
1268 各フィールドを異なる文で宣言しなければなりません。 |
|
1269 たとえば、次のドキュメンテー |
|
1270 ションコメントは単一の宣言としては意味を成さず、 |
|
1271 2 つの宣言として処理するべき |
|
1272 です。 |
|
1273 .LP |
|
1274 .RS |
|
1275 .ft 3 |
|
1276 .nf |
|
1277 /** |
|
1278 * The horizontal and vertical distances of point (x,y) |
|
1279 */ |
|
1280 public int x, y; // Avoid this |
|
1281 .fi |
|
1282 .ft 1 |
|
1283 .RE |
|
1284 .LP |
|
1285 .B javadoc |
|
1286 ツールは、上記コードから次のドキュメントを生成します。 |
|
1287 .LP |
|
1288 .RS |
|
1289 .ft 3 |
|
1290 public int x |
|
1291 .fi |
|
1292 .ft 1 |
|
1293 The horizontal and vertical distances of point |
|
1294 (x,y). |
|
1295 .ft 3 |
|
1296 .nf |
|
1297 public int y |
|
1298 .fi |
|
1299 .ft 1 |
|
1300 The horizontal and vertical distances of point |
|
1301 (x,y). |
|
1302 .RE |
|
1303 .LP |
|
1304 ヘッダタグを使用するときは注意してください。 |
|
1305 メンバ用のドキュメントコ |
|
1306 メントを書くときは、 |
|
1307 .B <H1> |
|
1308 や |
|
1309 .BR <H2> |
|
1310 などの HTML ヘッダタグを使用しないでください。これは、 |
|
1311 .B javadoc |
|
1312 が全ドキュメントを構造化して生成するため、 |
|
1313 これらの構造化タグを使用すると、 |
|
1314 ドキュメントの書式が乱れる可能性があるためです。 |
|
1315 しかし、クラスやパッケージの |
|
1316 コメントでは、これらのヘッダタグを使用して構造化を指示してください。 |
|
1317 .LP |
|
1318 メソッドコメントの自動コピー |
|
1319 .LP |
|
1320 .LP |
|
1321 Javadoc ツールには、次の 2 つの場合に、クラスおよびインタフェースのメソッドコメントをコピーまたは「継承」する機能があります。コンストラクタ、フィールド、および入れ子のクラスは、ドキュメンテーションコメントを継承しません。 |
|
1322 .LP |
|
1323 .RS 3 |
|
1324 .TP 2 |
|
1325 o |
|
1326 \f3自動的にコメントを継承して、見つからないテキストを埋める\fP \- 主説明または、\f2@return\fP、\f2@param\fP、\f2@throws\fP タグが、メソッドコメントで見つからない場合、Javadoc ツールは、オーバーライドしたメソッドまたは実装している場合はそのメソッドから、対応する主説明およびタグコメントを、次のアルゴリズムに従ってコピーします。 |
|
1327 .LP |
|
1328 厳密には、特定のパラメータの \f2@param\fP タグが見つからない場合、そのパラメータのコメントが、上位の継承階層のメソッドからコピーされます。特定の例外の \f2@throws\fP タグが見つからない場合、\f2その例外が宣言されている場合にかぎり\fP、その \f2@throws\fP タグがコピーされます。 |
|
1329 .LP |
|
1330 この動作はバージョン 1.3 以前の動作とは対照的です。これまでのバージョンでは、主説明またはタグが存在すれば、コメントは一切継承されませんでした。 |
|
1331 .TP 2 |
|
1332 o |
|
1333 \f3{@inheritDoc} タグを持つコメントを明示的に継承する\fP \- インラインタグ \f2{@inheritDoc}\fP を、メソッドの主説明、または \f2@return\fP、\f2@param\fP、\f2@throws\fP タグコメントに挿入します。継承した対応する主説明またはタグコメントは、その箇所にコピーされます。 |
|
1334 .RE |
|
1335 |
|
1336 .LP |
|
1337 .LP |
|
1338 ドキュメンテーションコメントを実際にコピーに利用するには、継承したメソッドのソースファイルが \-sourcepath で指定したパスだけに置かれていることが必要になります。コマンド行で、クラスもパッケージも渡す必要はありません。この点は、クラスが ドキュメント化されるクラスでなければならなかった 1.3.x 以前のリリースと異なります。 |
|
1339 .LP |
|
1340 .LP |
|
1341 \f3クラスおよびインタフェースからの継承\fP \- クラスおよびインタフェースから継承する次の 3 つの場合に、コメントの継承が行われます。 |
|
1342 .LP |
|
1343 .RS 3 |
|
1344 .TP 2 |
|
1345 o |
|
1346 クラスのメソッドがスーパークラスのメソッドをオーバーライドしている |
|
1347 .TP 2 |
|
1348 o |
|
1349 インタフェースのメソッドがスーパーインタフェースのメソッドをオーバーライドしている |
|
1350 .TP 2 |
|
1351 o |
|
1352 クラスのメソッドがインタフェースのメソッドを実装している |
|
1353 .RE |
|
1354 |
|
1355 .LP |
|
1356 .LP |
|
1357 最初の 2 つのケース (メソッドがオーバーライドしている場合) では、 |
|
1358 .B javadoc |
|
1359 ツールは、オーバーライドしているメソッドのドキュメント内に |
|
1360 「オーバーライド」という小見出しを生成し、コメントが継承されているかどうかにかかわらず、オーバーライドされている |
|
1361 メソッドへのリンクを書き込みます。 |
|
1362 .LP |
|
1363 3 つ目のケース (特定のクラスのメソッドがインタフェースの |
|
1364 メソッドを実装している場合) では、 |
|
1365 .B javadoc |
|
1366 ツールは、実装している |
|
1367 メソッドのドキュメント内に「定義」という小見出しを生成し、コメントが継承されているかどうかにかかわらず、 |
|
1368 実装されているメソッドへのリンクを書き込みます。 |
|
1369 .LP |
|
1370 メソッドの説明が継承されるアルゴリズム - あるメソッドに |
|
1371 ドキュメンテーションコメントが記述されていない場合、または {@inheritDoc} タグがある場合、 |
|
1372 .B javadoc |
|
1373 ツールは、次のようなアルゴリズムを使用して適切なコメントを検索します。 |
|
1374 このアルゴリズムは、もっとも適切なドキュメンテーションコメントを |
|
1375 検索できるように設計されており、スーパークラスよりも |
|
1376 インタフェースが優先されるようになっています。 |
|
1377 .TP 4 |
|
1378 1. |
|
1379 直接に実装されている (または、拡張されている) インタフェースを、 |
|
1380 メソッドの宣言で implements (または extends) キーワードのあとに |
|
1381 登場する順序で、1 つずつ調べる。 このメソッドについて |
|
1382 最初に見つかったドキュメンテーションコメントを採用する |
|
1383 .TP 4 |
|
1384 2. |
|
1385 手順 1 でドキュメンテーションコメントが見つからなかった場合は、 |
|
1386 直接実装されている (または、拡張されている) インタフェースの |
|
1387 それぞれに対して、このアルゴリズム全体を再帰的に適用する (その際の順序は、手順 1 でインタフェースを調べたときの順序と同じ) |
|
1388 .TP 4 |
|
1389 3. |
|
1390 手順 2 でドキュメンテーションコメントが見つからなかった場合で、 |
|
1391 このクラスが Object 以外のクラスである (インタフェースではない) 場合は、 |
|
1392 次のように処理する |
|
1393 .sp 1n |
|
1394 .nf |
|
1395 .ft 3 |
|
1396 a. スーパークラスにこのメソッドについてのドキュメンテーションコメントが記述されていれば、そのコメントを採用する |
|
1397 b. 手順 3a でドキュメンテーションコメントが見つからなかった場合は、スーパークラスに対して、このアルゴリズム全体を適用する |
|
1398 .ft 1 |
|
1399 .fi |
|
1400 .LP |
|
1401 .SS "javadoc のタグ" |
|
1402 .LP |
|
1403 .B javadoc |
|
1404 ツールは、 |
|
1405 .B java doc |
|
1406 コメント内に埋め込まれた特殊なタグを解析します。これらの |
|
1407 特殊な doc タグを使うと、 |
|
1408 書式の整った完全な API ドキュメントをソース |
|
1409 コードから自動的に生成できます。 |
|
1410 タグは、単価記号 (\f3@\f1) で始まり、大文字小文字が |
|
1411 区別されます。これらのタグは、 |
|
1412 以下に示すとおりに、大文字と小文字を区別して入力する |
|
1413 必要があります。タグは、行 |
|
1414 の先頭 (ただし先行する空白と省略可能なアスタリスクは除く) から |
|
1415 始めなければなり |
|
1416 ません。慣習上、同じ名前のタグは 1 個所にまとめて記述します。 |
|
1417 たとえば、 |
|
1418 .B @see |
|
1419 タグが複数ある場合は、すべてを 1 個所にまとめて記述します。 |
|
1420 .LP |
|
1421 タグは次の 2 種類あります。 |
|
1422 .LP |
|
1423 \(bu |
|
1424 スタンドアロンタグ - 説明のあとのタグセクションだけに |
|
1425 置くことができます。 このタグは、@tag のように中括弧で囲みません。 |
|
1426 .LP |
|
1427 \(bu |
|
1428 インラインタグ - コメントの説明内またはスタンドアロンタグの |
|
1429 コメント中の任意の場所に置くことができます。 インラインタグは、{@tag} の |
|
1430 ように中括弧で囲みます。 |
|
1431 .LP |
|
1432 今後のリリースで導入されるタグについては、 |
|
1433 .fi |
|
1434 http://java.sun.com/j2se/javadoc/proposed\-tags.html |
|
1435 の |
|
1436 .na |
|
1437 「\f2Proposed Tags\fP」を参照してください。 |
|
1438 .LP |
|
1439 .LP |
|
1440 現時点で有効なタグは、次のとおりです。 |
|
1441 .LP |
|
1442 .RS 3 |
|
1443 |
|
1444 .LP |
|
1445 .LP |
|
1446 .TS |
|
1447 center; |
|
1448 cbp-1 cbp-1 |
|
1449 l l. |
|
1450 タグ 導入された JDK/SDK のバージョン |
|
1451 @author 1.0 |
|
1452 {@code} 1.5 |
|
1453 {@docRoot} 1.3 |
|
1454 @deprecated} 1.0 |
|
1455 @exception 1.0 |
|
1456 {@inheritDoc} 1.4 |
|
1457 {@link} 1.2 |
|
1458 {@linkplain} 1.4 |
|
1459 {@literal} 1.5 |
|
1460 @param 1.0 |
|
1461 @return 1.0 |
|
1462 @see 1.0 |
|
1463 @serial 1.2 |
|
1464 @serialData 1.2 |
|
1465 @serialField 1.2 |
|
1466 @since 1.1 |
|
1467 @throws 1.2 |
|
1468 {@value} 1.4 |
|
1469 @version 1.0 |
|
1470 .TE |
|
1471 .if \n-(b.=0 .nr c. \n(.c-\n(d.-42 |
|
1472 |
|
1473 .LP |
|
1474 .LP |
|
1475 カスタムタグについては、\-tag オプションを参照してください。 |
|
1476 .TP |
|
1477 .BI @author " name-text" |
|
1478 .B \-author |
|
1479 オプションが使われている場合、 |
|
1480 生成されるドキュメントに、指定された |
|
1481 name-text を持つ Author エントリを追加します。 |
|
1482 1 つの doc コメントに複数の |
|
1483 .B @author |
|
1484 タグを含めることができます。 |
|
1485 .B @author |
|
1486 タグごとに 1 つ、またはタグごとに複数の名前を |
|
1487 指定できます。前者の場合は、 |
|
1488 .B javadoc |
|
1489 ツールは、名前と名前の間にコンマ (\f3,\f1) とスペースを挿入します。 |
|
1490 後者の場合、テキスト全体が |
|
1491 解析されることなく生成されるドキュメントにコピーされるだけです。 |
|
1492 このため、コンマ以外 |
|
1493 の現地仕様の名前区切り文字を使う場合は、1 行に複数の名前を指定します。 |
|
1494 .LP |
|
1495 詳細については、「タグを使用できる場所」および |
|
1496 .fi |
|
1497 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@author |
|
1498 の |
|
1499 .na |
|
1500 \f2@author タグのドキュメント\fPを参照してください。 |
|
1501 .LP |
|
1502 .TP 3 |
|
1503 @deprecated\ deprecated\-text |
|
1504 .RS 3 |
|
1505 |
|
1506 .LP |
|
1507 .LP |
|
1508 注: JDK 5.0 から、@Deprecated 注釈を使って特定のプログラム要素を非推奨にできるようになりました。 |
|
1509 .LP |
|
1510 この API は (動作はするが) 使用すべきでないことを示す |
|
1511 コメントを追加します。 |
|
1512 .B javadoc |
|
1513 は、deprecated-text を説明の前に移動してイタリックにし、 |
|
1514 その前にボールドの警告 |
|
1515 「推奨されません。」を追加します。このタグはすべての doc コメント (概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、フィールド) で有効です。 |
|
1516 .LP |
|
1517 .RS |
|
1518 deprecated-text の最初の文では、少なくともユーザにどのようなときに |
|
1519 その API が推奨されないか、およびそれに代わる API を提示する |
|
1520 必要があります。 |
|
1521 .B javadoc |
|
1522 は、最初の文だけを要約セクションと索引にコピーします。 |
|
1523 あとに続く文で、なぜその API が推奨されないかを |
|
1524 説明することもできます。代わりの API を |
|
1525 指し示す {\f3@link\f1} タグ ( |
|
1526 .B javadoc |
|
1527 1.2 以降の場合) を含める必要があります。 |
|
1528 .LP |
|
1529 詳細については、 |
|
1530 .fi |
|
1531 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@deprecated |
|
1532 の |
|
1533 .na |
|
1534 \f2@deprecated タグのドキュメント\fPを参照してください。 |
|
1535 .LP |
|
1536 .TP 2 |
|
1537 \(bu |
|
1538 .B javadoc |
|
1539 1.2 以降では、{\f3@link\f1} タグを使用してください。これにより、 |
|
1540 必要な場所にインラインで |
|
1541 リンクが作成されます。たとえば、次のように使います。 |
|
1542 .LP |
|
1543 .RS |
|
1544 .ft 3 |
|
1545 .nf |
|
1546 /** |
|
1547 * @deprecated As of JDK 1.1, replaced by |
|
1548 * {@link #setBounds(int,int,int,int)} |
|
1549 */ |
|
1550 .fi |
|
1551 .ft 1 |
|
1552 .RE |
|
1553 .LP |
|
1554 .TP 2 |
|
1555 \(bu |
|
1556 .B javadoc |
|
1557 1.1 では、各 |
|
1558 .B @deprecated |
|
1559 タグに |
|
1560 .B @see |
|
1561 タグ (インラインにできない) を作成するのが標準の形式です。 |
|
1562 .LP |
|
1563 推奨されないタグについての詳細は、「 |
|
1564 .B @deprecated |
|
1565 タグ」 を参照してください。 |
|
1566 .RE |
|
1567 .TP |
|
1568 .B {@code text} |
|
1569 <code>{@literal}</code> と同等です。 |
|
1570 .LP |
|
1571 テキストを HTML マークアップまたは |
|
1572 入れ子になった javadoc タグとして解釈せずに、 |
|
1573 テキストをコードフォントで表示します。 |
|
1574 これにより doc コメントでは、 |
|
1575 パラメータの種類 ( <Object> )、不等号 ( 3 < 4 )、 |
|
1576 または矢印 ( <- ) などで、HTML エンティティ ( < および > ) ではなく、 |
|
1577 通常の山括弧 (< および >) を使用できます。 |
|
1578 たとえば doc コメントのテキスト |
|
1579 .LP |
|
1580 .RS 5 |
|
1581 {@code A<B>C} |
|
1582 .RE |
|
1583 .LP |
|
1584 は、生成された HTML ページで、次のようにそのまま表示されます。 |
|
1585 .LP |
|
1586 .RS 5 |
|
1587 A<B>C |
|
1588 .RE |
|
1589 .LP |
|
1590 注目すべき点として、<B> は太字であると解釈されませんが、 |
|
1591 コードフォントになります。 |
|
1592 .LP |
|
1593 コードフォントなしで同じ機能を実現するには、 |
|
1594 {@literal} を使用します。 |
|
1595 .RE |
|
1596 .TP |
|
1597 .B {@docRoot} |
|
1598 生成された任意のページを起点とした、ドキュメントの (出力先) |
|
1599 ルートディレクトリの相対パスを表します。このタグは、著作権ページ |
|
1600 または会社のロゴなど、生成されるすべてのページから参照するファイル |
|
1601 を取り込むときに使います。通常は、各ページの最下部から著作権 |
|
1602 ページにリンクします。 |
|
1603 .RS |
|
1604 .LP |
|
1605 この \f2{@docRoot}\fP タグは、コマンド行からも、ドキュメンテーションコメントの中でも使用できます。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 |
|
1606 .TP 4 |
|
1607 1. |
|
1608 コマンド行では、次のようにヘッダ (header)、フッタ (footer)、 |
|
1609 またはページの最下部 (bottom)を定義します。 |
|
1610 .sp 1n |
|
1611 .B javadoc \-bottom '<a href="{@docRoot}/copyright.html">Copyright</a>' |
|
1612 .LP |
|
1613 注 - Makefile の中で {\f3@docRoot\f1}をこのように利用する場合、 |
|
1614 一部の Makefile プログラムでは、中括弧 { } 文字をエスケープする |
|
1615 必要があります。 たとえば、Inprise MAKE バージョン 5.2 を |
|
1616 Windows 上で実行する場合は、{{\f3@docRoot\f1}} のように、 |
|
1617 中括弧を二重にする必要があります。さらに、\-bottom などの |
|
1618 オプションに対する引数を、単一引用符ではなく、 |
|
1619 二重引用符で囲む必要があります。href |
|
1620 引数の値を囲む引用符は省略します。 |
|
1621 .TP |
|
1622 2. |
|
1623 doc コメントには次のように記述します。 |
|
1624 .sp 1n |
|
1625 .nf |
|
1626 .ft 3 |
|
1627 /** |
|
1628 * See the <a href="{@docRoot}/copyright.html">Copyright</a>. |
|
1629 */ |
|
1630 .ft 1 |
|
1631 .fi |
|
1632 .LP |
|
1633 このタグが必要な理由は、生成されるドキュメントが、サブパッケージと |
|
1634 同じ階層のディレクトリに格納されるためです。たとえば、次のように指定します。 |
|
1635 .LP |
|
1636 .ti +5n |
|
1637 .B <a href="{@docRoot}/copyright.html"> |
|
1638 .LP |
|
1639 次のように解決されます。 |
|
1640 .LP |
|
1641 .ti +5n |
|
1642 \f3<a href=".\|.\|/.\|.\|/copyright.html">\f1 .\|.\|. java/lang/Object.java の場合 |
|
1643 .sp 1n |
|
1644 および |
|
1645 .sp 1n |
|
1646 .ti +5n |
|
1647 \f3<a href=".\|.\|/.\|.\|/.\|.\|/copyright.html">\f1 .\|.\|. java/lang/ref/Reference.java の場合 |
|
1648 .RE |
|
1649 .TP |
|
1650 .BI @exception " class-name description" |
|
1651 .B @exception |
|
1652 タグは、 |
|
1653 .BR @throws |
|
1654 と同義です。 |
|
1655 .TP |
|
1656 {\f3@inheritDoc\f1} |
|
1657 最も近いスーパークラスから現在の ドキュメンテーションコメントに、ドキュメントを継承します。 この機能により、コメントは継承ツリーの上位に移動し、開発者はコピーしたテキストに記述を追加することができます。 |
|
1658 .LP |
|
1659 このタグは、ドキュメンテーションコメントの次の位置でのみ有効です。 |
|
1660 .RS 3 |
|
1661 .TP 2 |
|
1662 o |
|
1663 メソッドの主説明ブロック内。この場合、主説明は、上位階層のクラスまたはインタフェースからコピーされる |
|
1664 .TP 2 |
|
1665 o |
|
1666 メソッドの @return、@param、@throws タグのテキスト引数内。この場合、タグテキストは、上位階層の対応するタグからコピーされる |
|
1667 .RE |
|
1668 .LP |
|
1669 継承階層でコメントを見つける方法に関する正確な説明について、「メソッドコメントの自動コピー」を参照してください。このタグが見つからない場合、コメントは、この節で説明するルールに応じて、自動的に継承されるかどうかが決まります。 |
|
1670 .LP |
|
1671 .TP 3 |
|
1672 {@link\ package.class#member\ label} |
|
1673 表示テキスト label とのインラインリンクを挿入します。\f2label\fP は、参照クラスの指定されたパッケージ、クラス、またはメンバの名前のドキュメンテーションを指し示します。このタグは、@return、@param、@deprecated などの任意のタグのテキスト部分を含む、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。 |
|
1674 .LP |
|
1675 このタグは、 |
|
1676 .B @see |
|
1677 タグとよく似ています。どちらのタグも、package.class#member および |
|
1678 .BI label |
|
1679 の参照の仕方が同じで、有効な構文もまったく同じです。 |
|
1680 大きな違いは、{\f3@link\f1} は、リンクを [関連項目] セクションに |
|
1681 置くのではなく、インラインリンクを生成するということです。 |
|
1682 また、インラインテキストのほかの部分と区別するために、 |
|
1683 {\f3@link\f1} タグの最初と最後に中括弧を記述します。 |
|
1684 ラベルの中で「}」を使う必要がある場合は、HTML |
|
1685 エンティティの「}」を使います。 |
|
1686 .LP |
|
1687 1 つの文の中で使用できる {@link} タグの数に制限はありません。 |
|
1688 このタグは、ドキュメンテーションコメントの説明部分、または |
|
1689 .BR @deprecated |
|
1690 、 |
|
1691 .BR @return |
|
1692 、 |
|
1693 .BR @param |
|
1694 などの任意のタグのテキスト部分で使うことができます。 |
|
1695 .LP |
|
1696 たとえば、次のコメントでは、 |
|
1697 .B getComponentAt(int, int) |
|
1698 メソッドを参照しています。 |
|
1699 .LP |
|
1700 .ft 3 |
|
1701 .nf |
|
1702 Use the {\f3@link #getComponentAt(int, int) getComponentAt\f1} method. |
|
1703 .fi |
|
1704 .ft 1 |
|
1705 .LP |
|
1706 標準ドックレットでは、上記のコメントから次の HTML が |
|
1707 生成されます (このコメントが同じパッケージの別のクラスを参照している場合)。 |
|
1708 .LP |
|
1709 .ft 3 |
|
1710 .nf |
|
1711 Use the |
|
1712 <a href="Component.html#getComponentAt(int, int)">getComponentAt</a>method. |
|
1713 .fi |
|
1714 .ft 1 |
|
1715 .LP |
|
1716 この HTML は、Web ページ上では次のように表示されます。 |
|
1717 .LP |
|
1718 .ft 3 |
|
1719 .nf |
|
1720 Use the getComponentAt method. |
|
1721 .fi |
|
1722 .ft 1 |
|
1723 .LP |
|
1724 {\f3@link\f1} を、ドキュメント化の対象にしていないクラスにまで |
|
1725 拡張するには、 |
|
1726 .BR \-link |
|
1727 オプションを使用します。 |
|
1728 .LP |
|
1729 詳細については、 |
|
1730 .fi |
|
1731 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#{@link} |
|
1732 の |
|
1733 .na |
|
1734 \f2{@link} タグのドキュメント\fPを参照してください。 |
|
1735 .RE |
|
1736 .TP |
|
1737 {@linkplain package.class#member label} |
|
1738 リンクのラベルがコードフォントではなくプレーンテキストで |
|
1739 表示されている点以外は、 |
|
1740 {\f3@link\f1} と同じです。 ラベルがプレーンテキストで |
|
1741 記述されている場合に便利です。次の例を参照してください。 |
|
1742 .LP |
|
1743 .ft 3 |
|
1744 .nf |
|
1745 Refer to {\f3@linkplain\f1 add() the overridden method}. |
|
1746 .fi |
|
1747 .ft 1 |
|
1748 .LP |
|
1749 これは以下のように表示されます。 |
|
1750 .LP |
|
1751 .ft 3 |
|
1752 .nf |
|
1753 Refer to the overridden method. |
|
1754 .fi |
|
1755 .ft 1 |
|
1756 .LP |
|
1757 .TP |
|
1758 .B {@literal text} |
|
1759 テキストを HTML マークアップまたは |
|
1760 入れ子になった javadoc タグとして解釈せずに、 |
|
1761 テキストをコードフォントで表示します。 |
|
1762 これにより doc コメントでは、 |
|
1763 パラメータの種類 ( <Object> )、不等号 ( 3 < 4 )、 |
|
1764 または矢印 ( <- ) などで、HTML エンティティ ( < および > ) ではなく、 |
|
1765 通常の山括弧 (< および >) を使用できます。 |
|
1766 たとえば doc コメントのテキスト |
|
1767 .LP |
|
1768 .RS 5 |
|
1769 {@literal A<B>C} |
|
1770 .RE |
|
1771 .LP |
|
1772 は、生成された HTML ページはブラウザで次のようにそのまま表示されます。 |
|
1773 .LP |
|
1774 .RS 5 |
|
1775 A<B>C |
|
1776 .RE |
|
1777 .LP |
|
1778 注目すべき点として、<B> は太字であると解釈され、 |
|
1779 コードフォントになりません。 |
|
1780 .LP |
|
1781 コードフォントで同じ機能を実現するには、 |
|
1782 {@code} を使用します。 |
|
1783 .TP |
|
1784 .BI @param " parameter-name description" |
|
1785 指定した parameter-name と指定した description を使用して |
|
1786 パラメータを「Parameters」セクションに追加します。 |
|
1787 doc コメントを記述するときは、description を複数行に |
|
1788 続けることができます。このタグは、 |
|
1789 メソッド、コンストラクタ、またはクラスの |
|
1790 doc コメント内でのみ有効です。 |
|
1791 .LP |
|
1792 \f2parameter\-name\fP は、メソッドまたはコンストラクタでのパラメータの名前か、クラス、メソッドまたはコンストラクタのタイプパラメータの名前になります。 |
|
1793 山括弧でパラメータ名を囲むと、型パラメータを使用することを |
|
1794 指定します。 |
|
1795 .LP |
|
1796 クラスの型パラメータの例: |
|
1797 .nf |
|
1798 \f3 |
|
1799 .fl |
|
1800 /** |
|
1801 .fl |
|
1802 * @param <E> Type of element stored in a list |
|
1803 .fl |
|
1804 */ |
|
1805 .fl |
|
1806 public interface List<E> extends Collection<E> { |
|
1807 .fl |
|
1808 } |
|
1809 .fl |
|
1810 \fP |
|
1811 .fi |
|
1812 .LP |
|
1813 メソッドの型パラメータの例: |
|
1814 .nf |
|
1815 \f3 |
|
1816 .fl |
|
1817 /** |
|
1818 .fl |
|
1819 * @param string the string to be converted |
|
1820 .fl |
|
1821 * @param type the type to convert the string to |
|
1822 .fl |
|
1823 * @param <T> the type of the element |
|
1824 .fl |
|
1825 * @param <V> the value of the element |
|
1826 .fl |
|
1827 */ |
|
1828 .fl |
|
1829 <T, V extends T> V convert(String string, Class<T> type) { |
|
1830 .fl |
|
1831 } |
|
1832 .fl |
|
1833 \fP |
|
1834 .fi |
|
1835 詳細については、 |
|
1836 .fi |
|
1837 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@param |
|
1838 の |
|
1839 .na |
|
1840 \f2@param タグのドキュメント\fPを参照してください。 |
|
1841 .LP |
|
1842 .TP 3 |
|
1843 @return\ description |
|
1844 「戻り値」セクションを追加して、\f2description\fP のテキストを書き込みます。このテキストでは、戻り値の型と、取り得る値の範囲について記述する必要があります。このタグは、メソッドのドキュメンテーションコメントでのみ有効です。 |
|
1845 .LP |
|
1846 詳細については、 |
|
1847 .fi |
|
1848 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@return |
|
1849 の |
|
1850 .na |
|
1851 \f2@return タグのドキュメント\fPを参照してください。 |
|
1852 .LP |
|
1853 .TP 3 |
|
1854 @see\ reference |
|
1855 「関連項目」見出しを追加し、\f2reference\fP を指すリンクか、またはテキストエントリを書き込みます。1 つのドキュメンテーションコメントには、任意の数の \f2@see\fP タグを指定できます。すべての \f2@see\fP タグの内容は、同じ見出しの下にグループ化されます。\f2@see\fP タグには、次の 3 種類の形式があります。もっともよく使われるのは、3 番目の形式です。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。パッケージ、クラス、またはメンバに対するインラインリンクを文中に挿入する方法は、\f2{@link}\fP を参照してください。 |
|
1856 .RS 3 |
|
1857 .TP 3 |
|
1858 @see "string" |
|
1859 string のテキストエントリを追加します。 |
|
1860 リンクは生成されません。string は、書籍、または |
|
1861 URL ではアクセスできない情報の参照先です。 |
|
1862 .B javadoc |
|
1863 ツールは、最初の文字が二重引用符 (") かどうかを調べて、 |
|
1864 上の 2 つの形式とこの形式とを区 |
|
1865 別します。次に例を示します。 |
|
1866 .LP |
|
1867 .RS |
|
1868 .ft 3 |
|
1869 .nf |
|
1870 @see "The Java Programming Language" |
|
1871 .fi |
|
1872 .ft 1 |
|
1873 .LP |
|
1874 これは次のようなテキストを生成します。 |
|
1875 .LP |
|
1876 .ft 3 |
|
1877 .nf |
|
1878 関連項目: |
|
1879 "The Java Programming Language" |
|
1880 .fi |
|
1881 .ft 1 |
|
1882 .RE |
|
1883 .TP |
|
1884 \f3@see <a href="\f2URL#value\f3">\f2label\f3</a>\f1 |
|
1885 .IR URL#value |
|
1886 で定義されたとおりにリンクを追加します。 |
|
1887 .I URL#value |
|
1888 は、相対 URL または絶対 URL です。 |
|
1889 .B javadoc |
|
1890 ツールは、最初の文字として、小なり括弧 (\f3<\f1) を探すことで、 |
|
1891 このリンクをその他の場合と区別します。 |
|
1892 .LP |
|
1893 .RS |
|
1894 .ft 3 |
|
1895 .nf |
|
1896 @see <a href="spec.html#section">Java Spec</a> |
|
1897 .fi |
|
1898 .ft 1 |
|
1899 .LP |
|
1900 これは次のようなリンクを生成します。 |
|
1901 .LP |
|
1902 .ft 3 |
|
1903 .nf |
|
1904 関連項目: |
|
1905 Java Spec |
|
1906 .fi |
|
1907 .ft 1 |
|
1908 .RE |
|
1909 .TP |
|
1910 .BI @see " package.class#member label" |
|
1911 参照される Java 言語で指定された名前のドキュメントを指す、 |
|
1912 表示テキスト label を持つ |
|
1913 リンクを追加します。label は省略可能です。label を省略した場合は、 |
|
1914 該当する名前が |
|
1915 適切に短くされて (「名前の表示方法」を参照)、 |
|
1916 表示テキストとして代わりに表示されます。-noqualifier を使用すると、表示テキストからパッケージ名が全体的に削除されます。ラベルは、自動生成される表示テキストとは異なる表示テキストを指定する場合に使います。 |
|
1917 .LP |
|
1918 .RS |
|
1919 バージョン 1.2 では、ラベルではなく、名前だけが |
|
1920 HTML タグ |
|
1921 .B <code> |
|
1922 に囲まれて自動的に表示されます。バージョン 1.2.2 以降は、 |
|
1923 .B <code> |
|
1924 は常に、ラベルが使用されているかどうかにかかわらず、 |
|
1925 表示可能なテキストを囲みます。 |
|
1926 .TP 2 |
|
1927 \(bu |
|
1928 .I package.class#member |
|
1929 には、Java 言語で有効な任意の名前、つまりパッケージ、 |
|
1930 クラス、インタフェース、 |
|
1931 コンストラクタ、メソッド、またはフィールドの名前を指定します |
|
1932 。ただし、メンバ名の前の |
|
1933 ドットは、ハッシュ文字 (#) で置き換えます。 |
|
1934 指定した名前が、ドキュメント化されるクラス |
|
1935 にある場合、 |
|
1936 .B javadoc |
|
1937 ツールは該当する名前へのリンクを自動的に作成します。 |
|
1938 外部参照クラスへのリンクを作成する |
|
1939 には、 |
|
1940 .B \-link |
|
1941 オプションを使います。参照されるクラスに属していない名前の |
|
1942 ドキュメントを参 |
|
1943 照するには、ほかの 2 つの形式の |
|
1944 .B @see |
|
1945 タグを使います。1 番目の引数については、「名前の指定」 で |
|
1946 詳しく説明します。 |
|
1947 .TP 2 |
|
1948 \(bu |
|
1949 .I label |
|
1950 は省略可能なテキストで、 |
|
1951 リンクのラベルとして表示されます。label には空白を含 |
|
1952 めることができます。label を省略した場合は、 |
|
1953 .I package.class.member |
|
1954 が、現在のクラスおよびパッケージに応じて |
|
1955 適切に短くされて表示されます。「名前の表示方法」を参照してください。 |
|
1956 .TP 2 |
|
1957 \(bu |
|
1958 空白文字は |
|
1959 .I package.class#member |
|
1960 と |
|
1961 .IR label |
|
1962 の間の区切り文字です。括弧内の空白文字は、 |
|
1963 ラベルの開始を意味しないため、 |
|
1964 メソッドのパラメータ間のデリミタとして使うことができます。 |
|
1965 .LP |
|
1966 例-この例では、Character クラスの |
|
1967 .B @see |
|
1968 タグが String クラスの equals メソッドを参照しています。 |
|
1969 タグには、名前 \f3String#equals(Object)\f1 とラベル \f3equals\f1 の |
|
1970 両方の引数が含まれています。 |
|
1971 .LP |
|
1972 .ft 3 |
|
1973 .nf |
|
1974 /** |
|
1975 * @see String#equals(Object) equals |
|
1976 */ |
|
1977 .fi |
|
1978 .ft 1 |
|
1979 .LP |
|
1980 標準ドックレットは、次のような HTML を生成します。 |
|
1981 .LP |
|
1982 .ft 3 |
|
1983 .nf |
|
1984 <dl> |
|
1985 <dt><b>関連項目:</b> |
|
1986 <dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals</code></a> |
|
1987 </dl> |
|
1988 .fi |
|
1989 .ft 1 |
|
1990 .LP |
|
1991 これは、ブラウザでは次のように表示され、 |
|
1992 ラベルがリンクテキストになります。 |
|
1993 .LP |
|
1994 .ft 3 |
|
1995 .nf |
|
1996 関連項目: |
|
1997 equals |
|
1998 .fi |
|
1999 .ft 1 |
|
2000 .LP |
|
2001 .B 名前の指定: |
|
2002 この |
|
2003 .I package.class#member |
|
2004 の名前は、 |
|
2005 .BR java.lang.String#toUpperCase() |
|
2006 のように完全指定することも、 |
|
2007 .B String#toUpperCase() |
|
2008 や |
|
2009 .BR #toUpperCase() |
|
2010 などのように完全指定しないことも可能です。 |
|
2011 完全指定しない場合、 |
|
2012 .B javadoc |
|
2013 ツールは、通常の Java コンパイラの検索順序で検索を行います。 |
|
2014 詳細は、以下の「 |
|
2015 .BR @see |
|
2016 の検索順序」を参照してください。指定する名前では、 |
|
2017 メソッドの複数の引数の型の間など、 |
|
2018 括弧内に空白を含めることができます。 |
|
2019 .LP |
|
2020 短い部分修飾名を指定することの利点は、入力する |
|
2021 文字数が減ることと、ソースコードが |
|
2022 読みやすくなることです。以下の表に示すのは、さまざまな |
|
2023 形式の名前です。Class には |
|
2024 クラスかインタフェース、Type にはクラス、インタフェース、 |
|
2025 配列、または基本データ型、 |
|
2026 method にはメソッドまたはコンストラクタを指定できます。 |
|
2027 .LP |
|
2028 .LP |
|
2029 .TS |
|
2030 box; |
|
2031 lp-1. |
|
2032 @see package.class#member の一般的な形式 |
|
2033 _ |
|
2034 現在のクラスのメンバを参照する |
|
2035 @see #field |
|
2036 @see #method(Type, Type,...) |
|
2037 @see #method(Type argname, Type argname,...) |
|
2038 @see #constructor(Type, Type,...) |
|
2039 @see #constructor(Type argname, Type argname,...) |
|
2040 _ |
|
2041 T{ |
|
2042 現在の、またはインポートされたパッケージの別のクラスを参照する |
|
2043 T} |
|
2044 @see Class#field |
|
2045 @see Class#method(Type, Type,...) |
|
2046 @see Class#method(Type argname, Type argname,...) |
|
2047 @see Class#constructor(Type, Type,...) |
|
2048 T{ |
|
2049 @see Class#constructor(Type argname, Type argname,...) |
|
2050 T} |
|
2051 @see Class.NestedClass |
|
2052 @see Class |
|
2053 _ |
|
2054 別のパッケージの要素を参照する (完全修飾) |
|
2055 @see package.Class#field |
|
2056 @see package.Class#method(Type, Type,...) |
|
2057 @see package.Class#method(Type argname, Type argname,...) |
|
2058 @see package.Class#constructor(Type, Type,...) |
|
2059 T{ |
|
2060 @see package.Class#constructor(Type argname, Type argname,...) |
|
2061 T} |
|
2062 @see package.Class.NestedClass |
|
2063 @see package.Class |
|
2064 @see package |
|
2065 .TE |
|
2066 .LP |
|
2067 上の表に対する注を以下に示します。 |
|
2068 .LP |
|
2069 .TP 2 |
|
2070 \(bu |
|
2071 クラスまたはパッケージを省いた最初の形式のセットでは、 |
|
2072 .B javadoc |
|
2073 ツールは現在のクラス階層だけで検索を行います。 |
|
2074 .B javadoc |
|
2075 ツールは、現在のクラスかインタフェースのメンバ、スーパークラスか |
|
2076 スーパーインタフェースの 1 つ、または |
|
2077 親クラスかインタフェースの 1 つ (検索手順 1 〜 3) を検索します。 |
|
2078 現在のパッケージのほかの部分やほかのパッケージ (検索手順 4 〜 5) は |
|
2079 検索しません。 |
|
2080 .TP 2 |
|
2081 \(bu |
|
2082 メソッドまたはコンストラクタが、getValue のように |
|
2083 括弧を付けずに名前として入力され、 |
|
2084 かつ同じ名前のフィールドがない場合は、 |
|
2085 .B javadoc |
|
2086 ツールは正確にリンクを作成しますが、括弧と引数を追加するように |
|
2087 促す警告メッセージを出力 |
|
2088 します。このメソッドをオーバーロードした場合、 |
|
2089 .B javadoc |
|
2090 ツールは、指定されたメソッドではなく、検索で見つかった |
|
2091 最初のメソッドにリンクします。 |
|
2092 .TP 2 |
|
2093 \(bu |
|
2094 入れ子の内部クラスは、どの形式の場合でも、単に |
|
2095 .BR inner |
|
2096 という形ではなく、 |
|
2097 .BR outer.inner |
|
2098 という形で指定しなければなりません。 |
|
2099 .TP 2 |
|
2100 \(bu |
|
2101 すでに述べたとおり、クラスとメンバを区切るのに、ドット (\f3.\f1) ではなく |
|
2102 ハッシュ文字 (\f3#\f1) が |
|
2103 使われていることに注意してください。ドットは、クラス、 |
|
2104 入れ子のクラス、パッケージ、および |
|
2105 サブパッケージを区切るのにも使われます。 |
|
2106 ただし、 |
|
2107 .B javadoc |
|
2108 ツールでは一般に許容範囲が広く、 |
|
2109 あいまいさがなければ、ドットでも正しく解析されます。 |
|
2110 その場合でも警告は表示されます。 |
|
2111 |
|
2112 .LP |
|
2113 .B @see の検索順序: |
|
2114 .B javadoc |
|
2115 は、ソースファイル (\f3.java\f1)、パッケージ |
|
2116 ファイル (\f3package.html\f1 か \f3package\-info.java\f1)、または |
|
2117 概要ファイル (\f3overview.html\f1) 内で使われる |
|
2118 .B @see |
|
2119 タグを処理します。 |
|
2120 あとの 2 つのファイルでは、 |
|
2121 .BR @see |
|
2122 を使って指定する名前を完全修飾する必要があります。 |
|
2123 ソースファイルでは、完全修飾名 |
|
2124 と部分修飾名のどちらを指定することもできます。 |
|
2125 .LP |
|
2126 .B javadoc |
|
2127 ツールが、完全修飾されていない |
|
2128 .B .java |
|
2129 ファイルで |
|
2130 .B @see |
|
2131 タグを見つけた場合、指定された名前を Java コンパイラと |
|
2132 同じ順序で検索します。ただし、 |
|
2133 .B javadoc |
|
2134 ツールは、一部の名前空間のあいまいさは検出しません。これは、 |
|
2135 .B javadoc |
|
2136 ツールが、ソースコードにこれらのエラーが存在していないことを |
|
2137 前提として動作するためです。 |
|
2138 検索順序は、「Java Language Specification」第 2 版の第 6 章「Names」で |
|
2139 正式に定義されています。具体的には、検索は次の順序で行われます。 |
|
2140 .LP |
|
2141 .TP 4 |
|
2142 1. |
|
2143 現在のクラスまたはインタフェース |
|
2144 .PD 0 |
|
2145 .TP 4 |
|
2146 2. |
|
2147 名前を囲むクラスとインタフェース。もっとも近いものを最初に検索 |
|
2148 .TP 4 |
|
2149 3. |
|
2150 スーパークラスとスーパーインタフェース。もっとも近いものを最初に検索 |
|
2151 .TP 4 |
|
2152 4. |
|
2153 現在のパッケージ |
|
2154 .TP 4 |
|
2155 5. |
|
2156 インポートされるパッケージ、クラス、 |
|
2157 およびインタフェース。import 文の順序に従って検索 |
|
2158 .PD |
|
2159 .LP |
|
2160 .B javadoc |
|
2161 ツールは、一致する名前が見つかるまで、各クラスについて |
|
2162 手順 1 〜 3 を繰り返して検索を続け |
|
2163 ます。つまり、現在のクラスとそのクラスを囲む |
|
2164 クラス E を検索したあと、E のスーパクラスを |
|
2165 検索し、最後に E を囲むクラスを検索します。手順 4 と 5 では、 |
|
2166 .B javadoc |
|
2167 ツールは、1 つのパッケージ内でのクラスまたはインタフェースの検索を、 |
|
2168 なんらかの決まった順 |
|
2169 序で行うわけではありません (この検索順序はコンパイラに依存します)。 |
|
2170 手順 5 では、 |
|
2171 .B javadoc |
|
2172 ツールは、 |
|
2173 .BR java.lang |
|
2174 を検索します。これは、 |
|
2175 .BR java.lang |
|
2176 がすべてのプログラムによって自動的にインポートされるためです。 |
|
2177 .LP |
|
2178 .B javadoc |
|
2179 ツールは、必ずしもサブクラスを検索するわけではなく、Javadoc ツールの |
|
2180 実行中にほかのパッケージ |
|
2181 のドキュメントが生成される場合でも、ほかのパッケージの |
|
2182 検索は行いません。 |
|
2183 たとえば、 |
|
2184 .B @see |
|
2185 タグが |
|
2186 .B java.awt.event.KeyEvent |
|
2187 クラスにあって、 |
|
2188 .B java.awt |
|
2189 パッケージにある名前を参照する場合、 |
|
2190 .B javadoc |
|
2191 は、そのクラスがインポートしない限りそのパッケージを検索しません。 |
|
2192 .LP |
|
2193 .B 名前の表示方法: |
|
2194 .I label |
|
2195 が省略された場合は、 |
|
2196 .I package.class.member |
|
2197 が表示されます。通常、package.class.member は、現在の |
|
2198 クラスおよびパッケージに |
|
2199 応じて適切に短くされます。「短くされる」とは、 |
|
2200 .B javadoc |
|
2201 ツールが必要最小限の名前を表示するということです。 |
|
2202 たとえば、String.toUpperCase() メソッドが同じ |
|
2203 クラスのメンバへの参照と、別のクラスのメンバへの |
|
2204 参照を含んでいる場合、クラス名は後者の場合だけ表示されます。 |
|
2205 .LP |
|
2206 パッケージ名を広域的に削除するには、\-noqualifier を使用します。 |
|
2207 .br |
|
2208 .LP |
|
2209 .TP 4 |
|
2210 .TS |
|
2211 box, center; |
|
2212 cbp-1 | cbp-1 | cbp-1 |
|
2213 l | l | l . |
|
2214 参照の種類 T{ |
|
2215 String.toUppercase() での例 |
|
2216 T} 表示 |
|
2217 _ |
|
2218 T{ |
|
2219 @see タグが同じクラス、同じパッケージのメンバを参照している |
|
2220 T} T{ |
|
2221 @see String#toLowerCase() |
|
2222 T} T{ |
|
2223 toLowerCase() (パッケージおよびクラス名は省略) |
|
2224 T} |
|
2225 _ |
|
2226 T{ |
|
2227 @see タグが異なるクラス、同じパッケージのメンバを参照している |
|
2228 T} T{ |
|
2229 @see Character#toLowerCase(char) |
|
2230 T} T{ |
|
2231 Character.toLowerCase(char) (パッケージ名は省略し、クラス名を含む) |
|
2232 T} |
|
2233 _ |
|
2234 T{ |
|
2235 @see タグが異なるクラス、異なるパッケージのメンバを参照している |
|
2236 T} T{ |
|
2237 @see java.io.File#exists() |
|
2238 T} T{ |
|
2239 java.io.File.exists() (パッケージ名とクラス名を含む) |
|
2240 T} |
|
2241 .TE |
|
2242 .LP |
|
2243 \f3@see の例\fP |
|
2244 .br |
|
2245 右側のコメントは、\f2@see\fP タグが別のパッケージ (\f2java.applet.Applet\fP など) のクラス内にある場合に、名前がどのように表示されるかを示しています。 |
|
2246 .nf |
|
2247 \f3 |
|
2248 .fl |
|
2249 See also: |
|
2250 .fl |
|
2251 @see java.lang.String // String \fP\f3 |
|
2252 .fl |
|
2253 @see java.lang.String The String class // The String class \fP\f3 |
|
2254 .fl |
|
2255 @see String // String \fP\f3 |
|
2256 .fl |
|
2257 @see String#equals(Object) // String.equals(Object) \fP\f3 |
|
2258 .fl |
|
2259 @see String#equals // String.equals(java.lang.Object) \fP\f3 |
|
2260 .fl |
|
2261 @see java.lang.Object#wait(long) // java.lang.Object.wait(long) \fP\f3 |
|
2262 .fl |
|
2263 @see Character#MAX_RADIX // Character.MAX_RADIX \fP\f3 |
|
2264 .fl |
|
2265 @see <a href="spec.html">Java Spec</a> // Java Spec \fP\f3 |
|
2266 .fl |
|
2267 @see "The Java Programming Language" // "The Java Programming Language" \fP\f3 |
|
2268 .fl |
|
2269 \fP |
|
2270 .fi |
|
2271 .I @see |
|
2272 を、ドキュメント化の対象にしていないクラスにまで拡張するには、 |
|
2273 .I -link |
|
2274 オプションを使用します。 |
|
2275 .LP |
|
2276 詳細については、 |
|
2277 .fi |
|
2278 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@see |
|
2279 の |
|
2280 .na |
|
2281 \f2@see タグのドキュメント\fPを参照してください。 |
|
2282 .RE |
|
2283 .TP 3 |
|
2284 .BI @serial " field-description" | include | exclude |
|
2285 デフォルトの直列化可能フィールドの doc コメントで使用します。 |
|
2286 .RS |
|
2287 .LP |
|
2288 省略可能な field-description は、 |
|
2289 フィールドの doc コメントを拡張します。 |
|
2290 この説明では、フィールドの意味および |
|
2291 取り得る値のリストを指定しなければなりません。 |
|
2292 必要な場合には、複数の行にまたがって説明を記述することができます。 |
|
2293 標準ドックレットは、この情報を、直列化された形式のページに追加します。 |
|
2294 .LP |
|
2295 クラスを直列化したあとしばらくしてから直列化可能フィールドをクラスに追加した場合、主説明に、追加したバージョンを識別する文を追加する必要があります。 |
|
2296 .LP |
|
2297 .BR include |
|
2298 と |
|
2299 .BR exclude |
|
2300 引数は、直列化された形式のページにクラスまたはパッケージを含めるべきか、 |
|
2301 あるいはこれらの引数を除くべきかを指定します。 |
|
2302 これらは、次のように動作します。 |
|
2303 .LP |
|
2304 .TP 2 |
|
2305 \(bu |
|
2306 .BR Serializable |
|
2307 を実装する public クラスまたは protected クラスは、 |
|
2308 そのクラス (またはそのパッケージ) が |
|
2309 .BR @serial |
|
2310 .BR exclude |
|
2311 とマークされていない限り含められます。 |
|
2312 .TP 2 |
|
2313 \(bu |
|
2314 .BR Serializable |
|
2315 を実装する private クラスまたは package\-private クラスは、 |
|
2316 そのクラス (またはそのパッケージ) が |
|
2317 .BR @serial |
|
2318 .BR include |
|
2319 とマークされていない限り除かれます。 |
|
2320 .LP |
|
2321 例: |
|
2322 .BR javax.swing |
|
2323 パッケージは、(package.html または \f2package\-info.java\fP 内で) |
|
2324 .BR @serial |
|
2325 .BR exclude |
|
2326 とマークされます。 |
|
2327 public クラスである |
|
2328 .BR java.sercurity.BasicPermission |
|
2329 は、 |
|
2330 .BR @serial |
|
2331 .BR exclude |
|
2332 とマークされます。package\-private クラスである |
|
2333 .BR java.util.PropertyPermissionCollection |
|
2334 は、 |
|
2335 .BR @serial |
|
2336 .BR include |
|
2337 とマークされます。 |
|
2338 .LP |
|
2339 クラスレベルのタグ |
|
2340 .BR @serial |
|
2341 は、パッケージレベルの |
|
2342 .BR @serial |
|
2343 をオーバーライドします。 |
|
2344 .LP |
|
2345 これらのタグの使用法についての詳細と使用例は、「Java オブジェクト直列化仕様」の第 1.6 節「クラスの直列化可能なフィールドおよびデータの文書化」を参照してください。また、 |
|
2346 .fi |
|
2347 http://java.sun.com/products/jdk/serialization/faq/#javadoc_warn_missing |
|
2348 の |
|
2349 .na |
|
2350 「\f2直列化の FAQ\fP」も参照してください。この FAQ には、「\-private スイッチを指定しないで javadoc を実行しているのに private フィールドの @serial タグが見つからないという javadoc の警告が表示される」などの一般的な質問への回答が記載されています。直列化形式仕様にクラスを含める場合には、 |
|
2351 .fi |
|
2352 http://java.sun.com/j2se/javadoc/writingapispecs/serialized\-criteria.html |
|
2353 の |
|
2354 .na |
|
2355 「\f2Sun の仕様\fP」も参照してください。 |
|
2356 .LP |
|
2357 .RE |
|
2358 .TP |
|
2359 .BI @serialField " field-name field-type field-description" |
|
2360 Serializable クラスの serialPersistentFields メンバの ObjectStreamField コンポーネント |
|
2361 をドキュメント化します。各 ObjectStreamField コンポーネントに対して |
|
2362 .B @serialField |
|
2363 タグを 1 つ使う必要があります。 |
|
2364 .TP |
|
2365 .BI @serialData " data-description" |
|
2366 .I data-description |
|
2367 は、直列化された形式でのデータの型と順序を |
|
2368 説明するテキストです。 このデータには、 |
|
2369 特に、writeObject メソッドによって書き込まれる省略可能な |
|
2370 データ、および Externalizable.writeExternal メソッドによって |
|
2371 書き込まれるすべてのデータ (基底クラスを含む) が含まれます。 |
|
2372 .TP |
|
2373 .B @serialData |
|
2374 タグは、writeObject、readObject、writeExternal、および readExternal の各メソッドの |
|
2375 doc コメントで使用できます。 |
|
2376 .LP |
|
2377 .TP 3 |
|
2378 @since\ since\-text |
|
2379 生成ドキュメントに「導入されたバージョン」見出しを追加し、指定された \f2since\-text\fP を書き込みます。このテキストには、特別な内部構造はありません。このタグは、すべてのドキュメンテーションコメント、つまり概要、パッケージ、クラス、インタフェース、コンストラクタ、メソッド、およびフィールドで有効です。このタグは、特定の変更または機能が、\f2since\-text\fP に示されたソフトウェアリリース以降、存在していることを意味します。次に例を示します。 |
|
2380 .nf |
|
2381 \f3 |
|
2382 .fl |
|
2383 @since 1.5 |
|
2384 .fl |
|
2385 \fP |
|
2386 .fi |
|
2387 Java プラットフォームのソースコードの場合、このタグは、Java プラットフォーム API 仕様のバージョンを示します。その変更や機能がリファレンス実装に追加された時期を示すとは限りません。複数の @since タグを使用でき、複数の @author タグのように扱われます。プログラム要素が複数の API で使用される場合、複数のタグを使用できます。 |
|
2388 .RE |
|
2389 .TP |
|
2390 .BI @throws " class-name description" |
|
2391 .B @throws |
|
2392 タグと |
|
2393 .B @exception |
|
2394 タグは同義です。生成されるドキュメンテーションに、 |
|
2395 .I class-name |
|
2396 および |
|
2397 .I description |
|
2398 テキストを持つ [例外] 小見出しを追加します。 |
|
2399 .I class-name |
|
2400 は、該当するメソッドによって |
|
2401 スローされる可能性のある例外の名前です。このタグは、doc コメントまたはコンストラクタでのみ有効です。このクラスが完全 |
|
2402 修飾されていない場合、 |
|
2403 .B javadoc |
|
2404 ツールは検索順序に従ってクラスを探します。 |
|
2405 同じまたは異なる例外の doc コメントで、 |
|
2406 複数の @throws タグを使用できます。 |
|
2407 .LP |
|
2408 すべてのチェック済み例外がドキュメント化されるようにするために、 |
|
2409 @throws タグが throws 節内の例外用に存在しない場合は、 |
|
2410 @throws タグのあるドキュメントであるかのように、 |
|
2411 .B Javadoc |
|
2412 ツールによって例外が HTML 出力に説明なしで |
|
2413 自動的に追加されます。 |
|
2414 .LP |
|
2415 オーバーライドされたメソッドで明示的に例外が宣言されている場合に限って、 |
|
2416 オーバーライドされたメソッドからサブクラスへ |
|
2417 @throws ドキュメントがコピーされます。 |
|
2418 インタフェースメソッドから実装メソッドにコピーされる場合も |
|
2419 同様です。{@inheritDoc} を使用して、継承ドキュメントに対して |
|
2420 強制的に @throws を適用することも可能です。 |
|
2421 .LP |
|
2422 詳細は |
|
2423 .fi |
|
2424 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@exception |
|
2425 の |
|
2426 .na |
|
2427 \f2@throws タグのドキュメント\fPを参照してください。 |
|
2428 .TP |
|
2429 .B {@value package.class#field} |
|
2430 {@value} が静的フィールドの doc コメントで |
|
2431 引数なしで使用されている場合、その定数の値が表示されます。 |
|
2432 .LP |
|
2433 .RS 5 |
|
2434 .nf |
|
2435 /** |
|
2436 * The value of this constant is {@value}. |
|
2437 */ |
|
2438 public static final String SCRIPT_START = "<script>" |
|
2439 .fi |
|
2440 .RE |
|
2441 .LP |
|
2442 任意の doc コメント内で引数 |
|
2443 .B package.class#field |
|
2444 ありで使用されている場合は、指定した定数の値が表示されます。 |
|
2445 .LP |
|
2446 .RS 5 |
|
2447 .nf |
|
2448 /** |
|
2449 * Evaluates the script starting with {@value #SCRIPT_START}. |
|
2450 */ |
|
2451 public String evalScript(String script) { |
|
2452 } |
|
2453 .fi |
|
2454 .RE |
|
2455 .LP |
|
2456 引数 package.class#field は、@see 引数と同一の形式になります。 |
|
2457 ただし、メンバが静的フィールドになければならない点が異なります。 |
|
2458 .LP |
|
2459 これらの定数での値は、「定数フィールド値」ページにも表示されます。 |
|
2460 .TP |
|
2461 .BI @version " version-text" |
|
2462 \-version オプションが使われている場合、生成ドキュメントに「バージョン」小見出しを追加して、指定された \f2version\-text\fP を書き込みます。このタグは、このコードが含まれるソフトウェアの現在のバージョン番号を保持するように意図されています。これに対し、@since は、このコードが導入されたバージョン番号を保持します。\f2version\-text\fP には、特別な内部構造はありません。バージョンタグを使用できる場所を調べるには、「タグを使用できる場所」を参照してください。 |
|
2463 .LP |
|
2464 1 つのドキュメンテーションコメントに複数の \f2@version\fP タグを含めることができます。必要に応じて、\f2@version\fP タグごとに 1 つのバージョン番号を指定することも、タグごとに複数のバージョン番号を指定することもできます。前者の場合は、Javadoc ツールによって、名前と名前の間にコンマ (\f2,\fP) とスペースが挿入されます。後者の場合は、テキスト全体が、解析されることなく、生成ドキュメントにそのままコピーされます。したがって、コンマではなく、各言語に対応した名前区切り文字を使う必要がある場合は、1 つのタグに複数の名前を指定できます。 |
|
2465 .LP |
|
2466 詳細については、 |
|
2467 .fi |
|
2468 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@version |
|
2469 の |
|
2470 .na |
|
2471 \f2@version タグのドキュメント\fPを参照してください。 |
|
2472 .SS "タグを使用できる場所" |
|
2473 以下では、タグを使用できる場所について説明します。@see、@since、@deprecated、{@link}、{@linkplain} および {@docroot} のタグは、すべての doc コメントで使用できます。 |
|
2474 .SS "概要ドキュメントタグ" |
|
2475 概要タグは、概要ページのドキュメント |
|
2476 コメント (通常は \f3overview.html\f1 |
|
2477 という名前のソースファイル内にある) で使用できるタグです。 |
|
2478 ほかのドキュメント |
|
2479 コメントと同様に、これらのタグは、説明のあとで使う必要があります。 |
|
2480 .LP |
|
2481 注:バージョン 1.2 では、概要ドキュメント内の {\f3@link\f1} タグに |
|
2482 バグがあります。テキストは適切に表示されますが、 |
|
2483 リンクが設定されません。 |
|
2484 現在のところ、{\f2@docRoot\f1} タグは、 |
|
2485 概要ドキュメント内では動作しません。 |
|
2486 .LP |
|
2487 .LP |
|
2488 .TS |
|
2489 ; |
|
2490 cbp-1 |
|
2491 l . |
|
2492 概要タグ |
|
2493 @see |
|
2494 @since |
|
2495 @author |
|
2496 @version |
|
2497 {@link} |
|
2498 {@linkplain} |
|
2499 {@docRoot} |
|
2500 .TE |
|
2501 .if \n-(b.=0 .nr c. \n(.c-\n(d.-20 |
|
2502 |
|
2503 .LP |
|
2504 .SS "パッケージドキュメントタグ" |
|
2505 パッケージタグは、パッケージのドキュメント |
|
2506 コメント (\f3package.html\f1 または \f2package\-info.java\fP という |
|
2507 名前のソースファイルに存在) で使用できるタグです。 |
|
2508 ここで使用できる @serial タグは、include または |
|
2509 exclude 引数を指定したものだけです。 |
|
2510 .LP |
|
2511 .LP |
|
2512 .TS |
|
2513 ; |
|
2514 cbp-1 |
|
2515 l . |
|
2516 パッケージタグ |
|
2517 @see |
|
2518 @since |
|
2519 @serial |
|
2520 @author |
|
2521 @version |
|
2522 {@link} |
|
2523 {@linkplain} |
|
2524 {@docRoot} |
|
2525 .TE |
|
2526 .if \n-(b.=0 .nr c. \n(.c-\n(d.-22 |
|
2527 |
|
2528 .LP |
|
2529 .SS "クラスおよびインタフェースドキュメントタグ" |
|
2530 次に示すのは、クラスまたはインタフェースのドキュメント |
|
2531 コメントで使用できるタグです。 |
|
2532 ここで使用できる @serial タグは、 |
|
2533 include または exclude 引数を指定したものだけです。 |
|
2534 .LP |
|
2535 .LP |
|
2536 .TS |
|
2537 ; |
|
2538 cbp-1 |
|
2539 l . |
|
2540 クラスおよびインタフェースタグ |
|
2541 @see |
|
2542 @since |
|
2543 @deprecated |
|
2544 @serial |
|
2545 @author |
|
2546 @version |
|
2547 {@link} |
|
2548 {@linkplain} |
|
2549 {@docRoot} |
|
2550 .TE |
|
2551 |
|
2552 .LP |
|
2553 次は、クラスコメントの例です。 |
|
2554 .LP |
|
2555 .RS |
|
2556 .ft 3 |
|
2557 .nf |
|
2558 /** |
|
2559 * A class representing a window on the screen. |
|
2560 * For example: |
|
2561 * <pre> |
|
2562 * Window win = new Window(parent); |
|
2563 * win.show(); |
|
2564 * </pre> |
|
2565 * |
|
2566 * @author Sami Shaio |
|
2567 * @version 1.13, 06/08/06 |
|
2568 * @see java.awt.BaseWindow |
|
2569 * @see java.awt.Button |
|
2570 */ |
|
2571 class Window extends BaseWindow { |
|
2572 ... |
|
2573 } |
|
2574 .fi |
|
2575 .ft 1 |
|
2576 .RE |
|
2577 .SS "フィールドドキュメントタグ" |
|
2578 次に示すのは、フィールドのドキュメンテーションコメントで |
|
2579 使用できるタグです。 |
|
2580 .LP |
|
2581 .LP |
|
2582 .TS |
|
2583 ; |
|
2584 cbp-1 |
|
2585 l . |
|
2586 フィールドタグ |
|
2587 @see |
|
2588 @since |
|
2589 @deprecated |
|
2590 @serial |
|
2591 @serialField |
|
2592 {@link} |
|
2593 {@linkplain} |
|
2594 {@docRoot} |
|
2595 {@value} |
|
2596 .TE |
|
2597 .if \n-(b.=0 .nr c. \n(.c-\n(d.-24 |
|
2598 |
|
2599 .LP |
|
2600 次は、フィールドコメントの例です。 |
|
2601 .LP |
|
2602 .RS |
|
2603 .ft 3 |
|
2604 .nf |
|
2605 /** |
|
2606 * The X-coordinate of the component. |
|
2607 * |
|
2608 * @see #getLocation() |
|
2609 */ |
|
2610 int x = 1263732; |
|
2611 .fi |
|
2612 .ft 1 |
|
2613 .RE |
|
2614 .SS "コンストラクタおよびメソッドドキュメントタグ" |
|
2615 次に、コンストラクタまたはメソッドのドキュメンテーションコメント内で表示できるタグを示します。ただし、@return はコンストラクタでは表示できず、{@inheritDoc} は |
|
2616 表示に制限があります。@serialData タグは特定の直列化メソッドの doc コメントでのみ使用できます。 |
|
2617 .LP |
|
2618 .LP |
|
2619 .TS |
|
2620 ; |
|
2621 cbp-1 |
|
2622 l . |
|
2623 メソッドおよびコンストラクタタグ |
|
2624 @see |
|
2625 @since |
|
2626 @deprecated |
|
2627 @param |
|
2628 @return |
|
2629 @throws and @exception |
|
2630 @serialData |
|
2631 {@link} |
|
2632 {@linkplain} |
|
2633 {@inheritDoc} |
|
2634 {@docRoot} |
|
2635 .TE |
|
2636 .if \n-(b.=0 .nr c. \n(.c-\n(d.-28 |
|
2637 |
|
2638 .LP |
|
2639 次はメソッドの doc コメントの例です。 |
|
2640 .LP |
|
2641 .RS |
|
2642 .ft 3 |
|
2643 .nf |
|
2644 /** |
|
2645 * Returns the character at the specified index. An index |
|
2646 * ranges from <code>0</code> to <code>length() - 1</code>. |
|
2647 * |
|
2648 * @param index the index of the desired character. |
|
2649 * @return the desired character. |
|
2650 * @exception StringIndexOutOfRangeException |
|
2651 * if the index is not in the range <code>0</code> |
|
2652 * to <code>length()-1</code>. |
|
2653 * @see java.lang.Character#charValue() |
|
2654 */ |
|
2655 public char charAt(int index) { |
|
2656 ... |
|
2657 } |
|
2658 .fi |
|
2659 .ft 1 |
|
2660 .RE |
|
2661 .SH "オプション" |
|
2662 .B javadoc |
|
2663 ツールは、ドックレットを使って出力を決定します。 |
|
2664 .B javadoc |
|
2665 ツールは、 |
|
2666 .B \-doclet |
|
2667 オプションでカスタムドックレットが指定されている場合以外は、 |
|
2668 デフォルトの標準ドック |
|
2669 レットを使います。 |
|
2670 .B javadoc |
|
2671 ツールには、任意のドックレットとともに使用できるコマンド行 |
|
2672 オプションがあります。これらのオプ |
|
2673 ションについては、後述の「javadoc のオプション」で説明します。 |
|
2674 標準ドックレットでは、こ |
|
2675 のほかに、いくつかの追加のコマンド行オプションが提供されます。 |
|
2676 これらのオプションに |
|
2677 ついては、後述の「標準ドックレットが提供するオプション」で |
|
2678 説明します。どのオプション |
|
2679 名も大文字と小文字を区別しません。ただし、オプションの引数では |
|
2680 大文字と小文字が区 |
|
2681 別されることがあります。 |
|
2682 .LP |
|
2683 オプションを以下に示します。 |
|
2684 .LP |
|
2685 .RS 3 |
|
2686 |
|
2687 .LP |
|
2688 .LP |
|
2689 .TS |
|
2690 center; |
|
2691 li l li |
|
2692 l li li |
|
2693 li l li |
|
2694 l li li |
|
2695 li l l |
|
2696 l l li |
|
2697 li l li |
|
2698 l l l |
|
2699 l li l |
|
2700 l l li |
|
2701 li l l |
|
2702 li l l |
|
2703 l l l |
|
2704 li l l |
|
2705 li l l |
|
2706 l l li |
|
2707 li l l |
|
2708 l l l |
|
2709 l l l |
|
2710 l li l |
|
2711 l li l. |
|
2712 -1.1 -header -private |
|
2713 -author -help -protected |
|
2714 -bootclasspath -helpfile -public |
|
2715 -bottom -J -quiet |
|
2716 -breakiterator -keywords -serialwarn |
|
2717 -charset -link -source |
|
2718 -classpath -linkoffline -sourcepath |
|
2719 -d -linksource -splitindex |
|
2720 -docencoding -locale -stylesheetfile |
|
2721 -docfilessubdirs -nocomment -subpackages |
|
2722 -doclet -nodeprecated -tag |
|
2723 -docletpath -nodeprecatedlist -taglet |
|
2724 -doctitle -nohelp -tagletpath |
|
2725 -encoding -noindex -title |
|
2726 -exclude -nonavbar -use |
|
2727 -excludedocfilessubdir -noqualifier -verbose |
|
2728 -extdirs -nosince -version |
|
2729 -footer -notimestamp -windowtitle |
|
2730 -group -notree |
|
2731 -overview |
|
2732 -package |
|
2733 .TE |
|
2734 .if \n-(b.=0 .nr c. \n(.c-\n(d.-123 |
|
2735 |
|
2736 .LP |
|
2737 .RE |
|
2738 .LP |
|
2739 \f2下線付き\fPで示されたオプションは、Javadoc の基本オプションであり、Javadoc ツールのフロントエンドによって提供され、すべてのドックレットで使用できます。標準ドックレット自体は、下線付きでないオプションを提供します。 |
|
2740 .LP |
|
2741 .SS "Javadoc のオプション" |
|
2742 .TP |
|
2743 .BI \-overview " path/filename" |
|
2744 .B javadoc |
|
2745 に対して、 |
|
2746 .I path/filename |
|
2747 で指定された「ソース」ファイルから |
|
2748 概要ドキュメント用のテキスト |
|
2749 を取得し、概要ページ (\f3overview-summary.html\f1) に配置することを |
|
2750 指示します。 |
|
2751 .I path/filename |
|
2752 は、 |
|
2753 .BR \-sourcepath |
|
2754 への相対パスです。 |
|
2755 .LP |
|
2756 .RS |
|
2757 .I filename |
|
2758 と |
|
2759 .IR path |
|
2760 には、それぞれ任意の名前と場所を指定できますが、通常は、 |
|
2761 .B overview.html |
|
2762 という名前を付けて、ソースツリー内の最上位の |
|
2763 パッケージディレクトリを含むディレクトリ |
|
2764 に配置します。この場所では、 |
|
2765 .B \-sourcepath |
|
2766 がこのファイルを指すので、パッケージを |
|
2767 ドキュメント化する際に path が必要ありません。 |
|
2768 たとえば、java.lang パッケージのソースツリーが |
|
2769 .BR /src/classes/java/lang/ |
|
2770 の場合、概要ファイルを |
|
2771 .BR /src/classes/overview.html |
|
2772 に配置できます。「使用例」を参照してください。 |
|
2773 .LP |
|
2774 .IR path/filename |
|
2775 で指定するファイルについては、 |
|
2776 「概要コメントファイル」を参照してください。 |
|
2777 .LP |
|
2778 概要ページが作成されるのは、 |
|
2779 .B javadoc |
|
2780 に 2 つ以上のパッケージ名を渡した場合だけです。 |
|
2781 詳細は、「HTML フレーム」 |
|
2782 節を参照してください。 |
|
2783 .LP |
|
2784 概要ページのタイトルは、 |
|
2785 .B \-doctitle |
|
2786 によって設定されます。 |
|
2787 .RE |
|
2788 .TP |
|
2789 .B \-public |
|
2790 public なクラスとメンバだけを表示します。 |
|
2791 .TP |
|
2792 .B \-protected |
|
2793 protected および public なクラスとメンバだけを表示します。 |
|
2794 これはデフォルトの動作です。 |
|
2795 .TP |
|
2796 .B \-package |
|
2797 パッケージ、および protected と public な |
|
2798 クラスとメンバだけを表示します。 |
|
2799 .TP |
|
2800 .B \-private |
|
2801 すべてのクラスとメンバを表示します。 |
|
2802 .TP |
|
2803 .B \-help |
|
2804 オンラインヘルプを表示します。 |
|
2805 .B javadoc |
|
2806 とドックレットのコマンド行オプションの一覧が表示されます。 |
|
2807 .TP |
|
2808 .BI \-doclet " class" |
|
2809 ドキュメントの生成に使う |
|
2810 ドックレットを起動するためのクラスファイルを指定します。 |
|
2811 完全指定の名前を指定してください。 |
|
2812 ドックレットでは、出力の内容と形式を定義します。 |
|
2813 .B \-doclet |
|
2814 オプションが使われていない場合、 |
|
2815 .B javadoc |
|
2816 は標準ドックレットを使ってデフォルトの HTML 形式を生成します。 |
|
2817 このクラスには、 |
|
2818 start(Root) メソッドが含まれていなければなりません。 |
|
2819 この起動クラスへのパスは、 |
|
2820 .B \-docletpath |
|
2821 オプションによって定義されます。 |
|
2822 .LP |
|
2823 たとえば、MIF ドックレットを呼び出すには、次のように指定します。 |
|
2824 .LP |
|
2825 .RS |
|
2826 .ft 3 |
|
2827 .nf |
|
2828 -doclet com.sun.tools.doclets.mif.MIFDoclet |
|
2829 .fi |
|
2830 .ft 1 |
|
2831 .LP |
|
2832 特定のドックレットを実行した完全な例については、 |
|
2833 .fi |
|
2834 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet |
|
2835 の |
|
2836 .na |
|
2837 「\f2Running the MIF Doclet\fP」を参照してください。 |
|
2838 .RE |
|
2839 .TP |
|
2840 .BI \-docletpath " classpathlist" |
|
2841 .B \-doclet |
|
2842 オプションで指定されているドックレットクラスファイル、 |
|
2843 およびそれに依存する jar ファイルへのパスを指定します。 |
|
2844 起動クラスファイルが jar ファイル内にある場合、 |
|
2845 例に従って、その jar ファイルへのパスを指定します。 |
|
2846 絶対パス、または現在のディレクトリからの相対パスを指定できます。 |
|
2847 .IR classpathlist |
|
2848 には、複数のパスまたは jar ファイルを含める |
|
2849 ことができます。その場合、各パスまたは jar ファイルを Solaris ではコロン (\f3:\f1)で、Windows ではセミコロン (;) で区切ります。 |
|
2850 目的のドックレットの開始クラスがすでに検索パス内にある場合は、 |
|
2851 このオプションは不要です。 |
|
2852 .LP |
|
2853 次の例の jar ファイルへのパスには、ドックレットの |
|
2854 開始クラスファイルが含まれています。 |
|
2855 jar ファイル名が含まれている点に注意してください。 |
|
2856 .nf |
|
2857 \f3 |
|
2858 .fl |
|
2859 \-docletpath /home/user/mifdoclet/lib/mifdoclet.jar |
|
2860 .fl |
|
2861 \fP |
|
2862 .fi |
|
2863 次はドックレットの開始クラスファイルのパスの例です。 |
|
2864 クラスファイル名が省略されていることに注意してください。 |
|
2865 .nf |
|
2866 \f3 |
|
2867 .fl |
|
2868 \-docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/ |
|
2869 .fl |
|
2870 \fP |
|
2871 .fi |
|
2872 特定のドックレットを実行した完全な例については、 |
|
2873 .fi |
|
2874 http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet |
|
2875 の |
|
2876 .na |
|
2877 「\f2Running the MIF Doclet\fP」を参照してください。 |
|
2878 .RE |
|
2879 .LP |
|
2880 .TP |
|
2881 .B \-1.1 |
|
2882 この機能は、javadoc 1.4 から削除されました。代替の機能は |
|
2883 存在しません。このオプションは、javadoc 1.1 で生成される |
|
2884 ドキュメントの外観と機能 (サポートされなくなった、入れ子になったクラスを |
|
2885 含む) を備えたドキュメントを作成するためのものでした。 |
|
2886 このオプションが必要であれば、代わ |
|
2887 りに javadoc 1.2 または 1.3 を使用してください。 |
|
2888 .TP 3 |
|
2889 \-source release |
|
2890 受け付けるソースコードのバージョンを指定します。\f2release\fP には次の値を指定できます。 |
|
2891 .LP |
|
2892 .TS |
|
2893 ; |
|
2894 l l. |
|
2895 1.5 T{ |
|
2896 Javadoc は、JDK 1.5 で導入された総称機能および他の言語機能を含んだコードを受け付けます。-source フラグを指定しないと、コンパイラはデフォルトとして 1.5 の動作をします。 |
|
2897 T} |
|
2898 1.4 T{ |
|
2899 Javadoc は、JDK 1.4 で導入された、アサーションを含むコードを受け付けます。 |
|
2900 T} |
|
2901 1.3 T{ |
|
2902 Javadoc は、JDK 1.3 以降に導入されたアサーション、総称機能、または他の言語機能をサポートしません。 |
|
2903 T} |
|
2904 .TE |
|
2905 .if \n-(b.=0 .nr c. \n(.c-\n(d.-14 |
|
2906 .LP |
|
2907 javac でコードをコンパイルするときに使用した値に対応する \f2release\fP の値を使用します。 |
|
2908 .LP |
|
2909 .TP |
|
2910 .BI \-sourcepath " sourcepathlist" |
|
2911 .B javadoc |
|
2912 コマンドにパッケージ名または \-subpackages |
|
2913 を渡す際に、 |
|
2914 ソースファイル (.java) 検索用のパスを指定します。 |
|
2915 .BI sourcepathlist |
|
2916 には、コロン (\f3:\f1) |
|
2917 で区切った複数のパスを含めることができます。 |
|
2918 .B Javadoc |
|
2919 ツールは、指定されたパス以下のすべての |
|
2920 サブディレクトリを検索します。 このオプションを使って、 |
|
2921 ドキュメント化されるソースファイルの位置だけでなく、 |
|
2922 それ自体はドキュメント化されていないが、ドキュメント化 |
|
2923 されているソースファイルから継承されたコメントをもつ |
|
2924 ソースファイルの位置も確認できます。 |
|
2925 .LP |
|
2926 .B \-sourcepath |
|
2927 オプションは、 |
|
2928 .B javadoc |
|
2929 コマンドを使ってパッケージ名を指定するときにだけ使用でき、 |
|
2930 .B javadoc |
|
2931 コマンドに渡される |
|
2932 .B .java |
|
2933 ファイルは検索できないことに注意してください。 |
|
2934 .B .java |
|
2935 ファイルを検索するには、 |
|
2936 そのディレクトリに移動するか、 |
|
2937 各ファイルの前にそのパスを付けます (「1 つ以上 |
|
2938 のパッケージのドキュメント化」を参照)。 |
|
2939 .B \-sourcepath |
|
2940 が省略された場合は、 |
|
2941 .B javadoc |
|
2942 はクラスパスを使ってソースファイルを検索します ( |
|
2943 .B \-classpath |
|
2944 を参照)。 したがって、 |
|
2945 .B \-sourcepath |
|
2946 のデフォルトは |
|
2947 .B \-classpath |
|
2948 の値です。 |
|
2949 .B -classpath |
|
2950 を省略してパッケージ名を |
|
2951 .BR javadoc |
|
2952 に渡した場合、 |
|
2953 .BR javadoc |
|
2954 は、ソースファイルの現在のディレクトリ (およびサブディレクトリ) を |
|
2955 検索します。 |
|
2956 .LP |
|
2957 .RS |
|
2958 .I sourcepathlist |
|
2959 では、ドキュメント化するパッケージ名の |
|
2960 ソースツリーのルートディレクトリを |
|
2961 設定します。たとえば、ソースファイルが次の |
|
2962 場所にある |
|
2963 .B com.mypackage |
|
2964 という名前のパッケージをドキュメント化するとします。 |
|
2965 .LP |
|
2966 .RS |
|
2967 .ft 3 |
|
2968 .nf |
|
2969 /home/user/src/com/mypackage/*.java |
|
2970 .fi |
|
2971 .ft 1 |
|
2972 .RE |
|
2973 .LP |
|
2974 この場合、次のようにしてソースパスを |
|
2975 .BR /home/user/src |
|
2976 、つまり |
|
2977 .BR com.mypackage |
|
2978 を含むディレクトリに指定し、それからパッケージ名 |
|
2979 .BR com.mypackage |
|
2980 を指定します。 |
|
2981 .LP |
|
2982 .RS |
|
2983 .ft 3 |
|
2984 .nf |
|
2985 % javadoc \-sourcepath /home/user/src/ com.mypackage |
|
2986 .fi |
|
2987 .ft 1 |
|
2988 .RE |
|
2989 .LP |
|
2990 これは、ソースパスの値とパッケージ名をつなげて、 |
|
2991 ドットをスラッシュ (/) に変えると、以下のパッケージのフルパス |
|
2992 になることに注目すると覚えやすいでしょう。 |
|
2993 .LP |
|
2994 .RS |
|
2995 .ft 3 |
|
2996 .BR /home/user/src/com/mypackage |
|
2997 .RE |
|
2998 .LP |
|
2999 2 つのソースパスを指定するには、次のようにします。 |
|
3000 .LP |
|
3001 .RS |
|
3002 .ft 3 |
|
3003 .nf |
|
3004 % javadoc \-sourcepath /home/user/src/:/home/user2/src com.mypackage |
|
3005 .fi |
|
3006 .ft 1 |
|
3007 .RE |
|
3008 .LP |
|
3009 .RE |
|
3010 .TP |
|
3011 .BI \-classpath " classpathlist" |
|
3012 .B javadoc |
|
3013 が参照されるクラスの検索を行うパスを指定します。 |
|
3014 参照されるクラス (\f3.class\f1) とは、 |
|
3015 ドキュメント化されるクラスとそれらのクラスによって |
|
3016 参照される任意のクラスのことです。 |
|
3017 .B javadoc |
|
3018 は、指定されたパス以下のすべてのサブディレクトリで |
|
3019 検索を行います。 |
|
3020 .I classpathlist |
|
3021 には、パス間をコロン (\f3:\f1) で区切って複数のパスを |
|
3022 含めることができます。 |
|
3023 .B javadoc |
|
3024 ツールは、指定されたパス以下の |
|
3025 すべてのサブディレクトリを検索します。 |
|
3026 .IR classpathlist |
|
3027 の指定 |
|
3028 については、クラスパスのドキュメントを参照してください。 |
|
3029 .LP |
|
3030 .RS |
|
3031 .B \-sourcepath |
|
3032 を省略した場合は、 |
|
3033 .B javadoc |
|
3034 ツールは、クラスファイル (下位互換用) とともに、 |
|
3035 .B \-classpath |
|
3036 を使ってソースファイルを検索します。このため、 |
|
3037 異なるパス内のソースファイルおよびクラスファイルを検索する場合は、 |
|
3038 .B \-sourcepath |
|
3039 と |
|
3040 .BR \-classpath |
|
3041 の両方を使います。 |
|
3042 .LP |
|
3043 たとえば、 |
|
3044 .BR com.mypackage |
|
3045 をドキュメント化したい場合に、パッケージのクラスがディレクトリ |
|
3046 .BR /home/user/src/com/mypackage |
|
3047 にあり、このパッケージが |
|
3048 .BR /home/user/lib |
|
3049 内のライブラリを使う場合は、次のように指定します。 |
|
3050 .LP |
|
3051 .RS |
|
3052 .ft 3 |
|
3053 .nf |
|
3054 % javadoc \-classpath /home/user/lib \-sourcepath /home/user/src com.mypackage |
|
3055 .fi |
|
3056 .ft 1 |
|
3057 .RE |
|
3058 .LP |
|
3059 ほかのツールと同様に、 |
|
3060 .BR \-classpath |
|
3061 を指定しない場合は、CLASSPATH 環境変数が |
|
3062 設定されていれば、 |
|
3063 .B javadoc |
|
3064 ツールはこの環境変数を使います。 |
|
3065 どちらも設定されていない場合 |
|
3066 は、 |
|
3067 .B javadoc |
|
3068 ツールは現在のディレクトリでクラスを検索します。 |
|
3069 .LP |
|
3070 .B javadoc |
|
3071 ツールが拡張機能クラスおよびブートストラップクラスと通信する際に、 |
|
3072 .B -classpath |
|
3073 を使ってユーザクラスを検索する方法についての |
|
3074 詳細は、「クラスの検索方法」を |
|
3075 参照してください。 |
|
3076 .LP |
|
3077 便宜上、\f2*\fP のベース名を含むクラスパス要素は、ディレクトリ内の拡張子 \f2.jar\fP または \f2.JAR\fP を持つすべてのファイルのリストを指定するのと同じであるとみなされます (Java プログラムはこの 2 つの呼び出しを区別できない)。 |
|
3078 .br |
|
3079 .br |
|
3080 たとえば、ディレクトリ \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 プログラムが認識することはありません。 |
|
3081 .LP |
|
3082 .TP 3 |
|
3083 \-subpackages\ \ package1:package2:... |
|
3084 ソースファイルから指定されたパッケージおよびそのサブパッケージ内に再帰的にドキュメントを生成します。このオプションは、ソースコードに新しいサブパッケージを追加する際に便利です。新しいサブパッケージは自動的に組み込まれます。各 package 引数は、任意の最上位サブパッケージ (java など) または完全指定のパッケージ (javax.swing など) になります。ソースファイルを含める必要はありません。引数は、コロンで区切られます (すべてのオペレーティングシステム)。ワイルドカードは不要です (使用不可)。パッケージの検索場所を指定するには、\-sourcepath を使用します。このオプションは、「ソースファイルの処理」で説明したとおり、ソースツリーにあるがパッケージには属していないソースファイルを処理しないので役立ちます。 |
|
3085 .LP |
|
3086 次に例を示します。 |
|
3087 .nf |
|
3088 \f3 |
|
3089 .fl |
|
3090 % \fP\f3javadoc \-d docs \-sourcepath /home/user/src \-subpackages java:javax.swing\fP |
|
3091 .fl |
|
3092 .fi |
|
3093 このコマンドは、「java」および「javax.swing」という名前のパッケージとこれらのサブパッケージ全部のドキュメントを生成します。 |
|
3094 .LP |
|
3095 \f2\-exclude\fP とともに \f2\-subpackages\fP を使用すると、特定のパッケージを除外できます。 |
|
3096 .LP |
|
3097 .TP 3 |
|
3098 \-exclude\ \ packagename1:packagename2:... |
|
3099 指定されたパッケージとそのサブパッケージを \f2\-subpackages\fP によって作成されたリストから無条件に除外します。過去の \f2\-subpackages\fP オプションの指定によって組み込まれたパッケージ、または将来組み込まれるパッケージも除外の対象となります。次に例を示します。 |
|
3100 .nf |
|
3101 \f3 |
|
3102 .fl |
|
3103 % \fP\f3javadoc \-sourcepath /home/user/src \-subpackages java \-exclude java.net:java.lang\fP |
|
3104 .fl |
|
3105 .fi |
|
3106 このうち、\f2java.io\fP、\f2java.util\fP、\f2java.math\fP は組み込まれますが、\f2java.net\fP と \f2java.lang\fP 以下のパッケージは除外されます。ただし、\f2java.lang\fP のサブパッケージである \f2java.lang.ref\fP は除外されます。 |
|
3107 .RE |
|
3108 .TP |
|
3109 .BI \-bootclasspath " classpathlist" |
|
3110 ブートクラスが存在するパスを指定します。 |
|
3111 ブートクラスとは、Java プラットフォームクラスのことです。 |
|
3112 .B bootclasspath |
|
3113 は、 |
|
3114 .B javadoc |
|
3115 ツールがソースファイルとクラスファイルを探すときに |
|
3116 使う検索パスの一部です。詳細は、 |
|
3117 「Javac と Javadoc がクラスを検索する方法」 を |
|
3118 参照してください。 |
|
3119 .I classpathlist |
|
3120 内の複数の |
|
3121 クラスパスリストは、コロン (:) で区切ります。 |
|
3122 .TP |
|
3123 .BI \-extdirs " dirlist" |
|
3124 拡張機能クラスが存在するディレクトリを指定します。 |
|
3125 拡張機能クラスは、Java 拡張機能 |
|
3126 機構を使うすべてのクラスです。拡張機能ディレクトリ ( |
|
3127 .B extdirs |
|
3128 ) は、 |
|
3129 .B javadoc |
|
3130 ツールがソースファイルとクラスファイルを探すときに使う検索パスの一部です。 |
|
3131 詳細は、上の |
|
3132 .B \-classpath |
|
3133 を参照してください。 |
|
3134 .I dirlist |
|
3135 内の複数のディレクトリは、 |
|
3136 コロン (:) で区切ります。 |
|
3137 .TP |
|
3138 .B \-verbose |
|
3139 .B javadoc |
|
3140 の実行中に詳細なメッセージを表示します。冗長オプションを |
|
3141 指定しない場合は、ソースファイルのロード時、ドキュメントの |
|
3142 生成時 (ソースファイルごとに 1 つのメッセージ)、およびソート時に |
|
3143 メッセージが表示されます。冗長オプションを指定した場合は、 |
|
3144 各 java ソースファイルの解析に要したミリ秒数などの |
|
3145 追加メッセージを表示します。 |
|
3146 .TP |
|
3147 .BI \-quiet |
|
3148 エラーメッセージ以外、および警告メッセージ以外の |
|
3149 メッセージを除外し、 |
|
3150 エラーメッセージおよび警告メッセージだけを |
|
3151 表示して見つけやすくします。 |
|
3152 また、バージョン文字列の表示も抑制します。 |
|
3153 .LP |
|
3154 .TP 3 |
|
3155 \-breakiterator\ |
|
3156 英語言語というロケール固有のアルゴリズムではなく、\f2java.text.BreakIterator\fP の国際化された文境界を使用して、英文の最初の文の終わりを判断します (他のすべてのロケールはすでに \f2BreakIterator\fP を使用)。「\f2最初の文\fP」とは、パッケージ、クラス、またはメンバの主説明での最初の文のことです。この文は、パッケージ、クラス、またはメンバの要約にコピーされ、アルファベット順のインデックスにコピーされます。 |
|
3157 .LP |
|
3158 JDK 1.2 以降、BreakIterator クラスは、英語を除くすべての言語の文の終わりを判断するために、すでに使用されています。したがって、1.2 以降では、\f2\-breakiterator\fP オプションは英文以外には効果がありません。英文には、次のような独自のデフォルトのアルゴリズムがあります。 |
|
3159 .RS 3 |
|
3160 .TP 2 |
|
3161 o |
|
3162 英文のデフォルトの文区切りアルゴリズム \- 空白または HTML ブロックタグ (\f2<P>\fP など) が続くピリオドで停止する |
|
3163 .TP 2 |
|
3164 o |
|
3165 breakiterator 文区切りアルゴリズム \- 一般に、次の語が大文字で始まる場合、空白文字が続くピリオド、疑問符、または感嘆符で停止する。このアルゴリズムでは、ほとんどの省略表記が処理される (「The serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない。HTML タグに埋め込まれている場合でも、「../filename」の最後のピリオドで停止する |
|
3166 .RE |
|
3167 .RS 3 |
|
3168 .LP |
|
3169 .LP |
|
3170 注: 1.5.0 からは、1.4.x に設けられていた breakiterator 警告メッセージを削除し、デフォルトの文区切りアルゴリズムを変更していません。つまり、\-breakiterator オプションは、1.5.0 ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャーリリース」(1.5.0) でデフォルトを変更するという、以前の目的とは逆になっています。つまり、ソースコードを変更せず、1.4.x での breakiterator 警告を除去していない場合でも、1.5.0 からは何もする必要がなく、警告は消滅しています。この逆戻りの理由は、breakiterator をデフォルトにするメリットよりも、デフォルトにするために必要となる、互換性のないソースの変更の方が負担が大きかったためです。これに費やした作業や混乱が無駄になり残念です。 |
|
3171 .LP |
|
3172 .TP |
|
3173 .BI \-locale " language_country_variant" |
|
3174 .B 重要: |
|
3175 \-locale オプションは、標準ドックレットやその他のドックレット |
|
3176 によって提供されるオプションよりも前に (左側に) |
|
3177 指定する必要があります。そうでなければ、ナビゲーションバーは |
|
3178 英語で表示されます。順序に依存するコマンド行オプションは、 |
|
3179 このオプションのみです。 |
|
3180 .LP |
|
3181 .RS |
|
3182 .B javadoc |
|
3183 がドキュメントを生成するときに使うロケールを指定します。 |
|
3184 引数には、java.util.Locale のドキュメントで説明されている |
|
3185 ロケールを指定します。 |
|
3186 たとえば、en_US (英語、米国)、en_US_WIN (Windows で使われる英語) などを |
|
3187 指定します。 |
|
3188 .LP |
|
3189 ロケールを指定すると、 |
|
3190 .B javadoc |
|
3191 は指定されたロケールのリソースファイルを選択して |
|
3192 メッセージ (ナビゲーションバー、リストと表の見出し、 |
|
3193 ヘルプファイルの目次、 |
|
3194 .BR stylesheet.css |
|
3195 のコメントなどの文字列) に |
|
3196 使います。また、アルファベット順にソートされるリストのソート順、 |
|
3197 および最初の文の末尾を決定する文の区切り文字も、 |
|
3198 指定したロケールによって決まります。このオプションは、 |
|
3199 ドキュメント化されるクラスのソースファイル内で |
|
3200 指定されている doc コメントテキストの |
|
3201 ロケールを決定するものではありません。 |
|
3202 .RE |
|
3203 .TP |
|
3204 .BI \-encoding " name" |
|
3205 ソースファイルのエンコーディング名 (EUCJIS/SJIS など) を指定します。 |
|
3206 このオプションが指定されていない場合は、プラットフォームの |
|
3207 デフォルトコンバータが使われます。 |
|
3208 .LP |
|
3209 \-docencoding および \-charset も参照してください。 |
|
3210 .TP |
|
3211 .BI \-J flag |
|
3212 .BR javadoc |
|
3213 を実行する実行システム java に flag を直接渡します。J と flag の間に |
|
3214 空白を入れてはなりません。たとえば、生成される |
|
3215 ドキュメントを処理するために、システムで 32M バイトを |
|
3216 確保する必要がある場合は、Java の |
|
3217 .B \-Xmx |
|
3218 オプションを次のように呼び出します。\-Xms はオプションです。初期メモリのサイズのみを設定するため、必要な最小メモリを知っている場合に便利です。 |
|
3219 .LP |
|
3220 .RS |
|
3221 .ft 3 |
|
3222 .nf |
|
3223 % javadoc \-J\-Xmx32m \-J\-Xms32m com.mypackage |
|
3224 .fi |
|
3225 .ft 1 |
|
3226 .RE |
|
3227 |
|
3228 |
|
3229 .LP |
|
3230 使用している javadoc のバージョンを確認するには、 |
|
3231 次のように java の「-version」オプションを呼び出します。 |
|
3232 .LP |
|
3233 .RS |
|
3234 .ft 3 |
|
3235 .nf |
|
3236 % javadoc -J-version |
|
3237 java version "1.2" |
|
3238 Classic VM (build JDK-1.2-V, green threads, sunwjit) |
|
3239 .fi |
|
3240 .ft 1 |
|
3241 .RE |
|
3242 .LP |
|
3243 (標準ドックレットのバージョン番号は出力ストリームに表示されます。) |
|
3244 .SS "標準ドックレットが提供するオプション" |
|
3245 .TP |
|
3246 .BI \-d " directory" |
|
3247 生成された HTML ファイルを保存するディレクトリを |
|
3248 指定します (d は「生成先 (destination)」の意味)。このオプションを |
|
3249 省略すると、生成されたファイルは現在のディレクトリに保存されます。 |
|
3250 値 |
|
3251 .I directory |
|
3252 には、絶対ディレクトリまたは現在の作業 |
|
3253 ディレクトリからの相対ディレクトリを指定できます。 |
|
3254 1.4 では、javadoc の実行時に |
|
3255 自動的に生成先ディレクトリが作成されます。 |
|
3256 .LP |
|
3257 たとえば、 |
|
3258 次の例は、com.mypackage パッケージのドキュメントを生成し、 |
|
3259 結果を |
|
3260 .B /home/user/doc/ |
|
3261 ディレクトリに保存します。 |
|
3262 .LP |
|
3263 .RS |
|
3264 .ft 3 |
|
3265 .nf |
|
3266 % javadoc \-d /home/user/doc com.mypackage |
|
3267 .fi |
|
3268 .ft 1 |
|
3269 .RE |
|
3270 .TP |
|
3271 .B \-use |
|
3272 ドキュメント化されるクラスとパッケージごとに 1 つの [使用] ページを |
|
3273 含めます。このページには、ドキュメント化されるクラスまたは |
|
3274 パッケージの API を使っているパッケージ、クラス、メソッド、 |
|
3275 コンストラクタ、およびフィールドが記述されます。たとえば、クラス |
|
3276 C およびクラス C を使うものは、C のサブクラス、C として |
|
3277 宣言されているフィールド、C を返すメソッド、および、型 C の |
|
3278 パラメータを持つメソッドとコンストラクタがページに含ま |
|
3279 れます。 |
|
3280 .LP |
|
3281 .RS |
|
3282 たとえば、String について、[使用] ページに何が表示されるかを |
|
3283 見てみましょう。 |
|
3284 .B java.awt.Font |
|
3285 クラスの |
|
3286 .B getName() |
|
3287 メソッドは、String 型を返します。 |
|
3288 このため、 |
|
3289 .B getName() |
|
3290 は String を使うので、[使用] ページの String で |
|
3291 このメソッドを見つけることができます。 |
|
3292 .LP |
|
3293 このページでは API の使用だけがドキュメント化され、実装はドキュメント化されません。 |
|
3294 あるメソッドが実装内に String を使っているが、引数として |
|
3295 文字列をとったり、文字列を返したりしない |
|
3296 場合は、String の「使用」とはみなされません。 |
|
3297 .LP |
|
3298 生成された [使用] ページにアクセスするには、目的のクラスまたは |
|
3299 パッケージを表示して、ナビゲーションバーの [使用] リンクを |
|
3300 クリックします。 |
|
3301 .RE |
|
3302 .TP |
|
3303 .B \-version |
|
3304 生成されるドキュメントに |
|
3305 .B @version |
|
3306 テキストを含めます。このテキストは、デフォルトでは省略されます。 |
|
3307 使用している javadoc ツールのバージョンを確認するには、 |
|
3308 .B \-J\-version |
|
3309 オプションを使用します。 |
|
3310 .TP |
|
3311 .B \-author |
|
3312 生成されるドキュメントに |
|
3313 .B @author |
|
3314 テキストを含めます。 |
|
3315 .TP |
|
3316 .B \-splitindex |
|
3317 索引ファイルをアルファベットごとに複数のファイルに分割し、 |
|
3318 文字ごとに 1 つのファイルと、アルファベット以外の文字で始まる |
|
3319 索引エントリ用のファイルを 1 つ作成します。 |
|
3320 .TP |
|
3321 .BI \-windowtitle " title" |
|
3322 HTML の |
|
3323 .B <title> |
|
3324 タグで使うタイトルを指定します。指定したタイトルは、 |
|
3325 ウィンドウタイトルと、該当するページに対して作成されたブラウザの |
|
3326 ブックマーク (よくアクセスする場所) に表示されます。 |
|
3327 タイトルには HTML タグを含めないでください。タイトルに HTML タグが |
|
3328 含まれていると、ブラウザによるタグの解釈が不適切になる |
|
3329 可能性があります。 |
|
3330 .I title |
|
3331 の中で引用符を使う場合は、引用符を |
|
3332 エスケープする必要があります。 |
|
3333 .B -windowtitle |
|
3334 が省略されている場合、 |
|
3335 .B javadoc |
|
3336 ツールはこのオプションの代わりに -doctitle の値を使います。 |
|
3337 .LP |
|
3338 .RS |
|
3339 .ft 3 |
|
3340 .nf |
|
3341 % javadoc -windowtitle "Java 2 Platform" com.mypackage |
|
3342 .fi |
|
3343 .ft 1 |
|
3344 .RE |
|
3345 .TP |
|
3346 .BI \-doctitle " title" |
|
3347 概要ファイルの最上部近くに配置するタイトルを指定します。 |
|
3348 タイトルは中央揃えされ、レベル 1 の見出しとして上部 |
|
3349 ナビゲーションバーのすぐ下に置かれます。 |
|
3350 .I title |
|
3351 には、HTML タグと |
|
3352 空白を含めることができますが、これらを含める場合は全体を引用符で囲 |
|
3353 まなければなりません。 |
|
3354 .I title |
|
3355 の中で引用符を使う場合は、引用符をエスケープする必要があります。 |
|
3356 .LP |
|
3357 .RS |
|
3358 .ft 3 |
|
3359 .nf |
|
3360 % javadoc -doctitle "Java<sup><font size=\"-2\">TM</font></sup>" com.mypackage |
|
3361 .fi |
|
3362 .ft 1 |
|
3363 .RE |
|
3364 .TP |
|
3365 .BI \-title " title" |
|
3366 このオプションは、現在は存在しません。 |
|
3367 .B javadoc |
|
3368 1.2 のベータ版にだけ存在しました。このオプションは、 |
|
3369 ウィンドウタイトルではなくドキュメントタイトルを定義することを |
|
3370 明確にするため、 |
|
3371 .BR \-doctitle |
|
3372 に名前が変更されました。 |
|
3373 .TP |
|
3374 .BI \-header " header" |
|
3375 各出力ファイルの上部に配置するヘッダテキストを指定します。ヘッダは、 |
|
3376 上部ナビゲーションバーの右側に配置されます。 |
|
3377 .I header |
|
3378 には、HTML タグと |
|
3379 空白を含めることができますが、これらを含める場合は全体を引用符で |
|
3380 囲まなければなりません。header の中で引用符を使う場合は、引用符を |
|
3381 エスケープする必要があります。 |
|
3382 .nf |
|
3383 \f3 |
|
3384 .fl |
|
3385 % \fP\f3javadoc \-header "<b>Java 2 Platform </b><br>v1.4" com.mypackage\fP |
|
3386 .fl |
|
3387 .fi |
|
3388 .LP |
|
3389 .TP |
|
3390 .BI \-footer " footer" |
|
3391 各出力ファイルの下部に配置するフッタテキストを指定します。フッタは、 |
|
3392 下部ナビゲーションバーの右側に配置されます。 |
|
3393 .I footer |
|
3394 には、HTML タグと |
|
3395 空白を含めることができますが、これらを含める場合は全体を引用符で |
|
3396 囲まなければなりません。 |
|
3397 .I footer |
|
3398 の中で引用符を使う場合は、引用符をエスケープする必要があります。 |
|
3399 .TP |
|
3400 .BI \-bottom " text" |
|
3401 各出力ファイルの最下部に配置するテキストを指定します。 |
|
3402 このテキストは、下部ナビゲーションバーの下のページの最下部に |
|
3403 配置されます。 |
|
3404 .I text |
|
3405 には、HTML タグと空白を含めることができますが、 |
|
3406 これらを含める場合は全体を引用符で囲まなければなりません。 |
|
3407 .I text |
|
3408 の中で引用符を使う場合は、引用符をエスケープする必要があります。 |
|
3409 .TP |
|
3410 .BI \-link " extdocURL" |
|
3411 .B javadoc |
|
3412 ツールにより生成された既存の |
|
3413 外部参照クラスのドキュメンテーションへのリンクを作成します。 |
|
3414 引数は 1 つです。 |
|
3415 .TP |
|
3416 \(bu |
|
3417 .I extdocURL |
|
3418 は、javadoc によって生成され、リンク先として指定する |
|
3419 外部ドキュメントがあるディレクトリの絶対 URL または相対 URL です。 あとで例を示します。 このディレクトリ内に package-list ファイルが存在して |
|
3420 いなければなりません。存在しない場合は、\-linkoffline を使用します。 |
|
3421 .B javadoc |
|
3422 ツールは package-list ファイルからパッケージ名を読み取り、それを |
|
3423 .I extdocURL |
|
3424 のパッケージにリンクします。 javadoc ツールを実行すると、 |
|
3425 .I extdocURL |
|
3426 値は作成された <A HREF> リンクにそのままコピーされます。 したがって、 |
|
3427 .I extdocURL |
|
3428 はファイルではなく、 |
|
3429 .I extdocURL |
|
3430 の URL である必要があります。 |
|
3431 .LP |
|
3432 ドキュメントを任意の Web サイト上のドキュメントにリンクするには |
|
3433 .I extdocURL |
|
3434 の絶対リンクを、相対ロケーションだけを指定するには |
|
3435 相対リンクを使用できます。相対リンクを使用する場合、生成先ディレクトリ (\-d で指定) からの相対パスを、 |
|
3436 リンク先パッケージがあるディレクトリに渡す必要があります。 |
|
3437 .LP |
|
3438 通常、絶対リンクを指定する場合は、http: リンクを使用します。 |
|
3439 ただし、Web サーバをもたないファイルシステムに |
|
3440 リンクする場合は、file: リンクを使用できます。 |
|
3441 ただし、この方法は、生成されたドキュメントに |
|
3442 アクセスしようとする |
|
3443 すべてのユーザが同じファイルシステムを共有している |
|
3444 場合以外は使用しないでください。 |
|
3445 .LP |
|
3446 すべての場合、すべてのオペレーティングシステムで、絶対 URL と相対 URL、「http:」ベースと「file:」ベースにかかわらず、スラッシュを区切り文字として使用します |
|
3447 .fi |
|
3448 (http://www.ietf.org/rfc/rfc1738.txt |
|
3449 の |
|
3450 .na |
|
3451 \f2URL Memo\fP で指定)。 |
|
3452 .RS 3 |
|
3453 .TP 3 |
|
3454 http: ベースの絶対リンク: |
|
3455 \f2\-link http://<host>/<directory>/<directory>/.../<name>\fP |
|
3456 .TP 3 |
|
3457 file: ベースの絶対リンク: |
|
3458 \f2\-link file://<host>/<directory>/<directory>/.../<name>\fP |
|
3459 .TP 3 |
|
3460 相対リンク: |
|
3461 \f2\-link <directory>/<directory>/.../<name>\fP |
|
3462 .RE |
|
3463 .RE |
|
3464 .LP |
|
3465 javadoc 実行時に複数の \-link オプションを指定して、 |
|
3466 複数のドキュメントへのリンクを作成することもできます。 |
|
3467 .LP |
|
3468 \-linkoffline または \-link の選択 |
|
3469 .LP |
|
3470 \-link を使用する場合: |
|
3471 .TP 3 |
|
3472 \(bu |
|
3473 外部 API ドキュメントへの相対パスを使用している |
|
3474 .TP 3 |
|
3475 \(bu |
|
3476 外部 API ドキュメントへの絶対 URL を使用している (プログラムがその URL に接続し、読み取りを行うことが |
|
3477 シェルによって許可されている場合) |
|
3478 .LP |
|
3479 \-linkoffline を使用する場合: |
|
3480 .TP 3 |
|
3481 \(bu |
|
3482 外部 API ドキュメントへの絶対 URL を使用している |
|
3483 (プログラムがその URL に接続し、読み取りを行うことが |
|
3484 シェルによって許可されていない場合)。このような状況は、 |
|
3485 リンク先のドキュメントがファイアウォールの |
|
3486 向こう側にある場合に発生します。 |
|
3487 .LP |
|
3488 外部ドキュメントへの絶対リンクの使用例 - |
|
3489 java.lang、java.io、および他の Java 2 プラットフォームパッケージ |
|
3490 (\f2http://java.sun.com/j2se/1.5.0/docs/api\fP) に |
|
3491 リンクしたい場合があります。 |
|
3492 次のコマンドは、 |
|
3493 Java 2 プラットフォームパッケージへのリンクを持つ |
|
3494 com.mypackage パッケージのドキュメントを生成します。 |
|
3495 生成されたドキュメントには、たとえばクラスツリー内の |
|
3496 Object クラスへのリンクが含まれています |
|
3497 (\-sourcepath や \-d などの他のオプションは表示されません)。 |
|
3498 .LP |
|
3499 .RS |
|
3500 .ft 3 |
|
3501 .nf |
|
3502 % \fP\f3javadoc \-link http://java.sun.com/j2se/1.5.0/docs/api com.mypackage\fP |
|
3503 .fi |
|
3504 .ft 1 |
|
3505 .RE |
|
3506 .LP |
|
3507 外部 ドキュメントへの相対リンクの使用例 - |
|
3508 .B javadoc |
|
3509 ツールの異なる実行で生成されたドキュメントを持つ |
|
3510 2 つのパッケージがあり、それらが別々の |
|
3511 相対パスをもっているとします。 |
|
3512 この例では、2 つのパッケージを |
|
3513 com.apipackage (API)、com.spipackage |
|
3514 (SPI - Service Provide Interface) とします。 ドキュメントの置き場所は docs/api/com/apipackage および |
|
3515 docs/spi/com/spipackage です。 |
|
3516 API パッケージドキュメントはすでに生成され、ドキュメントが現在の |
|
3517 ディレクトリ内にある場合、次のように実行することで、 |
|
3518 API ドキュメントにリンクした SPI パッケージをドキュメント化できます。 |
|
3519 .LP |
|
3520 .RS |
|
3521 .ft 3 |
|
3522 .nf |
|
3523 % javadoc \-d ./spi \-link ../api com.spipackage |
|
3524 .fi |
|
3525 .ft 1 |
|
3526 .RE |
|
3527 .LP |
|
3528 \-link 引数が生成先ディレクトリの相対パス (docs/spi) で |
|
3529 あることに注意してください。 |
|
3530 .LP |
|
3531 詳細 - |
|
3532 \-link オプションを使うと、コードからは参照されていても、 |
|
3533 Javadoc の現在の実行ではドキュメント化されないクラスにリンク |
|
3534 できるようになります。 リンクから有効なページに |
|
3535 移動できるようにするには、それらの HTML ページが |
|
3536 ある場所を調べ、その場所を |
|
3537 .I extdocURL |
|
3538 に指定する必要があります。 |
|
3539 このオプションを使うと、たとえば、サードパーティのドキュメントから、 |
|
3540 http://java.sun.com にある java.* のドキュメントにリンクすることができます。 |
|
3541 .LP |
|
3542 今回の実行で |
|
3543 .B javadoc |
|
3544 によって生成されるドキュメント内の |
|
3545 API だけを対象にリンクを作成する場合は、 |
|
3546 \-link オプションを省略します。 \-link オプションが |
|
3547 指定されていない場合、 |
|
3548 .B javadoc |
|
3549 ツールは、外部参照されたドキュメントへのリンクを |
|
3550 作成しません。これは、そのドキュメントが |
|
3551 存在するかどうか、あるいは存在していてもどこに |
|
3552 存在しているのかを判別できないからです。 |
|
3553 .LP |
|
3554 このオプションは、生成ドキュメント内の複数の場所に |
|
3555 リンクを作成できます。 |
|
3556 .LP |
|
3557 また、このオプションを使うと、複数のパッケージ群の間にクロスリンクを作成することもできます。つまり、ある一式のパッケージに対して javadoc を実行したあと、別の一式のパッケージに対して javadoc を実行し、これら 2 つのパッケージ群の間にクロスリンクを作成できます。 |
|
3558 .LP |
|
3559 \f3クラスの参照方法\fP - 外部参照クラスへのリンクを、テキストラベルだけではなく実際に表示するには、次の方法でクラスを参照する必要があります。メソッドの本体でクラスを参照するだけでは十分ではありません。\f2import\fP 文または宣言で参照する必要があります。次に、クラス \f2java.io.File\fP を参照する方法の例を示します。 |
|
3560 .RS 3 |
|
3561 .TP 2 |
|
3562 o |
|
3563 すべての種類の \f2import\fP 文の場合: ワイルドカードによるインポート、名前による明示的なインポート、または \f2java.lang.*\fP に対する自動的なインポート。たとえば、次のようにすれば十分です。 |
|
3564 .br |
|
3565 \f2import java.io.*;\fP |
|
3566 .br |
|
3567 1.3.x および 1.2.x では、名前による明示的なインポートだけです。ワイルドカードによるインポート文も、自動インポート \f2java.lang.*\fP も使用できません。 |
|
3568 .TP 2 |
|
3569 o |
|
3570 宣言の場合: |
|
3571 .br |
|
3572 \f2void foo(File f) {}\fP |
|
3573 .br |
|
3574 この参照を使用し、メソッド、コンストラクタ、フィールド、クラス、またはインタフェースのリターンタイプまたはパラメータタイプに置くか、\f2implements\fP、\f2extends\fP、または \f2throws\fP 文に置きます。 |
|
3575 .RE |
|
3576 .LP |
|
3577 この結果、\f2\-link\fP オプションを使用しても、この制限のために誤って表示されない多くのリンクが多数発生する可能性があります。テキストはハイパーテキストリンクが付けられずに表示されます。これらのリンクが表示する警告から、このリンクを認識できます。クラスを正しく参照し、それによってリンクを追加するためのもっとも安全な方法は上で説明したとおり、当該のクラスをインポートすることです。 |
|
3578 .LP |
|
3579 .B パッケージリスト: |
|
3580 .B \-link |
|
3581 オプションでは、javadoc ツールによって生成された |
|
3582 .BR package-list |
|
3583 という名前のファイルが、このオプションで指定する URL に存在している |
|
3584 必要があります。 |
|
3585 .BR package-list |
|
3586 ファイルは、その場所でドキュメント化されているパッケージの |
|
3587 名前のリストを含む単純なテキストファイルです。 |
|
3588 前の例では、 |
|
3589 .B javadoc |
|
3590 ツールは、指定された URL にある |
|
3591 .BR package-list |
|
3592 という名前のファイルを探し、パッケージ名を読み込んで、 |
|
3593 その URL にあるそれらのパッケージへのリンクを作成しました。 |
|
3594 .LP |
|
3595 たとえば、Java プラットフォーム v5.0 API のパッケージリストは以下にあり、 |
|
3596 .na |
|
3597 \f2http://java.sun.com/j2se/1.5.0/docs/api/package\-list\fP |
|
3598 .RE |
|
3599 .LP |
|
3600 次のような内容で始まっています。 |
|
3601 .LP |
|
3602 .RS |
|
3603 .ft 3 |
|
3604 .nf |
|
3605 java.applet |
|
3606 java.awt |
|
3607 java.awt.color |
|
3608 java.awt.datatransfer |
|
3609 java.awt.dnd |
|
3610 java.awt.event |
|
3611 java.awt.font |
|
3612 その他 ... |
|
3613 .fi |
|
3614 .ft 1 |
|
3615 .RE |
|
3616 .LP |
|
3617 .B \-link |
|
3618 オプションを指定せずに |
|
3619 .B javadoc |
|
3620 ツールを実行した場合、ドキュメントの生成時に外部参照 |
|
3621 クラスに属する名前を |
|
3622 見つけると、 |
|
3623 .B javadoc |
|
3624 はその名前をリンクを持たない形で出力します。一方、 |
|
3625 .B \-link |
|
3626 オプションが指定されている場合、 |
|
3627 .B javadoc |
|
3628 ツールは、指定された |
|
3629 .IR extdocURL |
|
3630 の場所にある |
|
3631 .B package-list |
|
3632 ファイルから、該当する名前のパッケージを探します。パッケージ名が |
|
3633 見つかった場合は、その |
|
3634 .IR extdocURL |
|
3635 を名前の前に付けます。 |
|
3636 .LP |
|
3637 すべてのリンクが正しく機能するためには、外部参照の |
|
3638 ドキュメントのすべてが、指定された URL に |
|
3639 存在していなければなりません。 |
|
3640 .B javadoc |
|
3641 ツールは、 |
|
3642 .B package-list |
|
3643 が存在するかどうかを調べるだけで、指定された URL に |
|
3644 目的のページが存在するかどうかはチェックしません。 |
|
3645 .LP |
|
3646 .B 複数のリンク: |
|
3647 複数の |
|
3648 .B \-link |
|
3649 オプションを提供して、外部で生成されたドキュメントに任意数のリンクを設定できます。Javadoc 1.2 には、複数の |
|
3650 .B -link |
|
3651 コマンドを提供できないというバグがあります。このバグは、 |
|
3652 1.2.2 で修正されました。 |
|
3653 .LP |
|
3654 リンクする外部ドキュメントごとに別のリンクオプションを指定します。 |
|
3655 .LP |
|
3656 .RS |
|
3657 .ft 3 |
|
3658 .nf |
|
3659 % javadoc \-link extdocURL1 \-link extdocURL2 ... \-link extdocURLn com.mypackage |
|
3660 .fi |
|
3661 .ft 1 |
|
3662 .RE |
|
3663 .LP |
|
3664 .BR extdocURL1、 |
|
3665 .BR extdocURL2、... |
|
3666 .BR extdocURLn |
|
3667 は、それぞれ外部ドキュメントの |
|
3668 ルートを指し、各ルートには、 |
|
3669 .BR package-list |
|
3670 という名前のファイルが含まれています。 |
|
3671 .LP |
|
3672 クロスリンク - まだ生成されていない 2 つ以上のドキュメントを |
|
3673 クロスリンクする場合は、「ブートストラッピング」が必要になることに |
|
3674 注意してください。言い換えると、どのドキュメントの |
|
3675 .B package-list |
|
3676 も存在していない場合、最初のドキュメントに対して |
|
3677 .B javadoc |
|
3678 ツールを実行した時点では、2 番目のドキュメントの |
|
3679 .B package-list |
|
3680 はまだ存在していません。したがって、外部リンクを作成するには、 |
|
3681 2 番目のドキュメントを |
|
3682 生成したあと、最初のドキュメントを生成し直す必要があります。 |
|
3683 .LP |
|
3684 この場合、最初に行うドキュメント生成の目的は、 |
|
3685 .B package-list |
|
3686 を作成することです。パッケージ名をすべて把握している場合は、 |
|
3687 .B package-list |
|
3688 を手動で作成することもできます。次に、2 番目のドキュメントと |
|
3689 その外部リンクを生成します。 |
|
3690 .B javadoc |
|
3691 ツールは、必要な外部の |
|
3692 .B package-list |
|
3693 ファイルが存在しない場合は、警告を表示します。 |
|
3694 .TP |
|
3695 .BI \-linkoffline " extdocURL packagelistLoc" |
|
3696 このオプションは、 |
|
3697 .BR \-link |
|
3698 オプションを変えたものです。どちらも、javadoc で |
|
3699 生成された外部参照クラスのドキュメントへのリンクを作成します。 |
|
3700 .B Javadoc |
|
3701 ツールが「オフライン」で、Web 上のドキュメントに |
|
3702 リンクする場合は、Web 接続経由ではドキュメントに |
|
3703 アクセスできないため、 |
|
3704 .B \-linkoffline |
|
3705 オプションを使用します。 |
|
3706 .LP |
|
3707 厳密には、外部ドキュメントの \f2package\-list\fP ファイルにアクセスできないとき、またはこのファイルが \f2extdocURL\fP で指定された場所とは異なる場所 (通常、\f2packageListLoc\fP で指定可能なローカルな場所) に存在するとき、\f2\-linkoffline\fP を使用します。したがって、\f2extdocURL\fP に WWW 上でしかアクセスできない場合は、\f2\-linkoffline\fP を指定することにより、ドキュメントの生成時に javadoc ツールが Web に接続できなければならないという制約がなくなります。 |
|
3708 .LP |
|
3709 さらに、ドキュメントを更新するための「ハッキング」としての使用も可能です。パッケージのセット全体に対して javadoc を実行したあと、変更した一部のパッケージだけに対して javadoc を実行します。こうして、更新されたファイルを、オリジナルのファイルセットに挿入できるようにします。例をあとで示します。 |
|
3710 .LP |
|
3711 .BR \-linkoffline |
|
3712 オプションには 2 つの引数があります。1 つは |
|
3713 <a href> リンクに埋め込む文字列、もう 1 つは |
|
3714 .BR package-list: |
|
3715 の検索場所を示します。 |
|
3716 .LP |
|
3717 .RS |
|
3718 .TP 2 |
|
3719 \(bu |
|
3720 .I extdocURL |
|
3721 は、\f3javadoc\f1 によって生成され、リンク先として指定する |
|
3722 外部ドキュメントがあるディレクトリの絶対 |
|
3723 URL または相対 URL です。 相対リンクの場合、 |
|
3724 生成先ディレクトリ (\-d で指定) からの相対パスを、 |
|
3725 リンク先パッケージのルートに渡す必要があります。 詳細は、 |
|
3726 .B \-link |
|
3727 オプションの |
|
3728 .I extdocURL |
|
3729 を参照してください。 |
|
3730 .TP 2 |
|
3731 \(bu |
|
3732 .I packagelistLoc |
|
3733 には、外部ドキュメントの |
|
3734 .B package-list |
|
3735 ファイルが入っているディレクトリのパスまたは |
|
3736 URL を指定します。 URL (http: または file:) |
|
3737 またはファイルパスを指定できます。 |
|
3738 また、絶対パスと相対パスのどちらでもかまいません。 |
|
3739 相対パスの場合は、javadoc が実行される現在の |
|
3740 ディレクトリからの相対パスとして指定します。 |
|
3741 .BR package-list |
|
3742 というファイル名は含めないでください。 |
|
3743 .LP |
|
3744 .B javadoc |
|
3745 の 1 回の実行で、複数の |
|
3746 .B \-linkoffline |
|
3747 オプションを指定できます。 |
|
3748 1.2.2 より前のバージョンでは、複数のオプションは指定できませんでした。 |
|
3749 .LP |
|
3750 外部ドキュメントへの絶対リンクを使った例 - |
|
3751 .BR java.lang |
|
3752 、 |
|
3753 .BR java.io |
|
3754 、およびその他の Java 2 プラットフォームパッケージ (\f2http://java.sun.com/j2se/1.5.0/docs/api\fP) |
|
3755 にリンクしたくても、Web にアクセスできない |
|
3756 場合について考えてみます。 |
|
3757 .BR package-list |
|
3758 ファイルをブラウザで開き (\f2http://java.sun.com/j2se/1.5.0/docs/api/package\-list\fP)、 |
|
3759 ローカルディレクトリに保存します。 |
|
3760 次に、2 番目の引数 |
|
3761 .I packagelistLoc |
|
3762 でそのローカルコピーを指定します。このとき |
|
3763 パッケージリストファイルは現在のディレクトリ |
|
3764 「.」に保存されています。 次のコマンドは、 |
|
3765 Java 2 プラットフォームパッケージへのリンクを含む、 |
|
3766 com.mypackage パッケージのドキュメントを生成します。 |
|
3767 生成されたドキュメントには、たとえばクラスツリー内の |
|
3768 Object クラスへのリンクが含まれています |
|
3769 (\-sourcepath などの他の必要なオプションは表示されません)。 |
|
3770 .LP |
|
3771 .RS |
|
3772 .ft 3 |
|
3773 .nf |
|
3774 % \fP\f3javadoc \-linkoffline http://java.sun.com/j2se/1.5.0/docs/api . com.mypackage\fP |
|
3775 .fi |
|
3776 .ft 1 |
|
3777 .RE |
|
3778 .LP |
|
3779 外部ドキュメントへの相対リンクを使った例 - |
|
3780 .B \-linkoffline |
|
3781 を相対パスで指定するのはあまり一般的ではありません。通常は、 |
|
3782 .B \-link |
|
3783 で十分だからです。 |
|
3784 .B \-linkoffline |
|
3785 を使用している場合、 |
|
3786 .BR package-list |
|
3787 ファイルは通常ローカルで、相対リンクを使用している場合は、 |
|
3788 リンク先のファイルもローカルであるのが普通です。 |
|
3789 そのため、 |
|
3790 .B \-linkoffline |
|
3791 に 2 つの異なる引数のパスを |
|
3792 与える必要はありません。 2 つの引数が同じである場合、 |
|
3793 .B \-link |
|
3794 を使用できます。 |
|
3795 .B \-link |
|
3796 の相対リンクの使用例を参照してください。 |
|
3797 .LP |
|
3798 package-list ファイルの手動作成 - |
|
3799 .BR package-list |
|
3800 ファイルがまだ存在しなくても、ドキュメントのリンク先のパッケージ名がわかっている場合は、このファイルのコピーを自分で作成し、 |
|
3801 .I packagelistLoc |
|
3802 でそのパスを指定することができます。 |
|
3803 com.apipackage が最初に作成されたときに |
|
3804 com.spipackage のパッケージリストが存在しなかった、 |
|
3805 以前の場合がその例です。 |
|
3806 この方法は、パッケージ名はわかっているものの、 |
|
3807 まだ公開されていない、新しい外部ドキュメントにリンクする |
|
3808 ドキュメントを生成する場合に便利です。 |
|
3809 また、Javadoc 1.0 または 1.1 では package-list ファイルが |
|
3810 生成されないため、この方法で、これらのバージョンで |
|
3811 生成されたパッケージの package-list ファイルを生成できます。 |
|
3812 2 つの会社が未公開の package-list ファイルを |
|
3813 共有することもできるため、クロスリンクを設定した |
|
3814 ドキュメントを同時にリリースすることも可能です。 |
|
3815 .LP |
|
3816 複数のドキュメントにリンク - |
|
3817 .B \-linkoffline |
|
3818 は、参照先の生成ドキュメントごとに 1 つずつ指定します。 |
|
3819 次の例では、わかりやすくするために |
|
3820 オプションごとに行を分けています。 |
|
3821 .LP |
|
3822 .RS |
|
3823 .ft 3 |
|
3824 .nf |
|
3825 .ta 18n |
|
3826 % javadoc \-linkoffline docURL1 packagelistURL1 \\ |
|
3827 \-linkoffline docURL2 packagelistURL2 \\ |
|
3828 .ft 1 |
|
3829 ... |
|
3830 .fi |
|
3831 .RE |
|
3832 .LP |
|
3833 .B ドキュメントの更新: |
|
3834 .B \-linkoffline |
|
3835 オプションのもう 1 つの用途は、プロジェクトで多数のパッケージを使い、 |
|
3836 すでにツリー全体に対して |
|
3837 .B javadoc |
|
3838 を実行してある場合に、次の実行では、すばやく細かい |
|
3839 変更を行なってから、ソース |
|
3840 ツリーの一部に対してだけ |
|
3841 .B javadoc |
|
3842 を実行し直したい場合に便利です。これは、 |
|
3843 変更がドキュメンテーションコメントに対し |
|
3844 てであり、シグニチャに対してではない場合にだけ正常に |
|
3845 処理されるので、ハッキング |
|
3846 のようなものです。ソースコードに対してシグニチャを追加、 |
|
3847 削除または変更した場合は、索引、パッケージツリー、 |
|
3848 継承されるメンバのリスト、[使用] ページなどの場所 |
|
3849 で壊れたリンクが表示されます。 |
|
3850 .LP |
|
3851 まず、新しい実行のため、新規の |
|
3852 生成先ディレクトリ (update) を作成します。オリジナルの生成先ディレクトリを html とします。もっとも簡単な例として、html の親に移動します。 |
|
3853 .B \-linkoffline |
|
3854 の 1 番目の引数に現在のディレクトリ「.」を |
|
3855 設定し、2 番目の引数に package-list |
|
3856 を検索する場所である html への相対パスを設定します。更新したいパッケージのパッケージ名のみを渡します。 |
|
3857 .LP |
|
3858 .RS |
|
3859 .ft 3 |
|
3860 .nf |
|
3861 % javadoc \-d update \-linkoffline . html com.mypackage |
|
3862 .fi |
|
3863 .ft 1 |
|
3864 .RE |
|
3865 .LP |
|
3866 .B javadoc |
|
3867 の実行が終了したとき、 |
|
3868 .B update/com/package |
|
3869 内に生成されたクラス (概要や索引ではない) で、 |
|
3870 html/com/package 内にあるオリジナルのファイルを上書きコピーします。 |
|
3871 .TP |
|
3872 \-linksource |
|
3873 各ソースファイル (行番号付き) の HTML バージョンを作成し、標準 HTML ドキュメントからソースファイルへのリンクを追加します。リンクは、ソースファイル内に宣言されているクラス、インタフェース、コンストラクタ、メソッド、フィールドに対して作成されます。デフォルトコンストラクタ、生成されたクラスに対しては作成されません。 |
|
3874 .LP |
|
3875 \f3このオプションは、\fP\f4\-public\fP\f3、\fP\f4\-package\fP\f3、\fP\f4\-protected\fP\f3、\fP\f4\-private\fP\f3 の各オプションとは関係なく、非公開のクラス、フィールド、非公開のメソッドの本体をはじめとする組み込まれたソースファイル内の\fP\f4すべての\fP\f3非公開実装の詳細を公開します。\fP\f2\-private\fP オプションを指定しないかぎり、非公開のクラスやインタフェースの一部には、リンクを介してアクセスできないことがあります。 |
|
3876 .LP |
|
3877 各リンクは、その宣言内の識別子名の上に作成されます。たとえば、\f2Button\fP クラスのソースコードヘのリンクは、「Button」という語の上に作成されます。 |
|
3878 .nf |
|
3879 \f3 |
|
3880 .fl |
|
3881 public class Button |
|
3882 .fl |
|
3883 extends Component |
|
3884 .fl |
|
3885 implements Accessible |
|
3886 .fl |
|
3887 \fP |
|
3888 .fi |
|
3889 Button クラスの \f2getLabel()\fP メソッドのソースコードへのリンクは、「getLabel」という語の上に作成されます。 |
|
3890 .nf |
|
3891 \f3 |
|
3892 .fl |
|
3893 public String getLabel() |
|
3894 .fl |
|
3895 \fP |
|
3896 .fi |
|
3897 .LP |
|
3898 .TP |
|
3899 .BI \-group " groupheading packagepattern:packagepattern:..." |
|
3900 概要ページの複数のパッケージを指定のグループに分け、 |
|
3901 グループ単位で表を作成 |
|
3902 します。各グループは、それぞれ別の |
|
3903 .B \-group |
|
3904 オプションで指定します。これらのグループは、 |
|
3905 コマンド行で指定した順序でページに |
|
3906 表示されます。パッケージは、1 つのグループ内では |
|
3907 アルファベット順に並べられます。各 |
|
3908 .B \-group |
|
3909 オプションでは、 |
|
3910 .I packagepattern |
|
3911 式のリストに一致する |
|
3912 パッケージが、見出し |
|
3913 .IR groupheading |
|
3914 を持つ 1 つの表にまとめて表示されます。 |
|
3915 .RS |
|
3916 .TP 2 |
|
3917 \(bu |
|
3918 .I groupheading |
|
3919 には任意のテキストを指定でき、空白を含めることができます。 |
|
3920 指定したテキストは、グループの表見出しになります。 |
|
3921 .TP 2 |
|
3922 \(bu |
|
3923 .I packagepattern |
|
3924 には、任意のパッケージ名、または任意のパッケージ名の先頭部分とそれに続く 1 つのアスタリスク (*)を指定できます。 |
|
3925 アスタリスクは、「任意の文字に一致する」という意味のワイルドカードです。ワイルドカードとして許容されるのは、アスタリスクだけです。1 つのグループには、 |
|
3926 コロン (:) で区切った複数のパターンを含めることができます。 |
|
3927 .LP |
|
3928 注: パターンやパターンリスト内でアスタリスクを |
|
3929 使う場合は、"java.lang*:java.util" |
|
3930 のように、パターンリストを引用符で囲む必要があります。 |
|
3931 .LP |
|
3932 .B \-group |
|
3933 オプションが 1 つも指定されていない場合は、すべての |
|
3934 パッケージが、[パッケージ] |
|
3935 という見出しを持つ 1 つのグループに入れられます。 |
|
3936 ドキュメント化されるパッケージの |
|
3937 中に、指定したグループのどのグループにも入らない |
|
3938 パッケージがある場合、このような |
|
3939 パッケージは [その他のパッケージ] という見出しを |
|
3940 持つ独立したグループに入れられます。 |
|
3941 .LP |
|
3942 たとえば、次のようにオプションを指定すると、 |
|
3943 ドキュメント化される 4 つのパッケージは、 |
|
3944 コアパッケージ、拡張機能パッケージ、 |
|
3945 およびその他のパッケージに分かれます。 |
|
3946 \f3java.lang*\f1 では、後続のドットがないことに |
|
3947 注意してください。\f3java.lang.*\f1 のようにドットを |
|
3948 入れると、 |
|
3949 .B java.lang |
|
3950 パッケージは含まれないことになります。 |
|
3951 .LP |
|
3952 .RS |
|
3953 .ft 3 |
|
3954 .nf |
|
3955 % javadoc \-group "Core Packages" "java.lang*:java.util" |
|
3956 \-group "Extension Packages" "javax.*" |
|
3957 java.lang java.lang.reflect java.util javax.servlet java.new |
|
3958 .fi |
|
3959 .ft 1 |
|
3960 .RE |
|
3961 .LP |
|
3962 この結果、次のようなグループ化が行われます。 |
|
3963 .LP |
|
3964 .RS |
|
3965 .ft 3 |
|
3966 .nf |
|
3967 Core Packages |
|
3968 java.lang |
|
3969 java.lang.reflect |
|
3970 java.util |
|
3971 Extension Packages |
|
3972 javax.servlet |
|
3973 Other Packages |
|
3974 java.new |
|
3975 .fi |
|
3976 .ft 1 |
|
3977 .RE |
|
3978 .RE |
|
3979 .TP |
|
3980 .B \-nodeprecated |
|
3981 推奨されない API をドキュメントに生成することを禁止します。 |
|
3982 これは、 |
|
3983 .B \-nodeprecatedlist |
|
3984 オプションを指定した場合の動作に加えて、 |
|
3985 ドキュメントのほかの部分を通じて、 |
|
3986 推奨されない API を生成しないことと同じです。 |
|
3987 このオプションは、コードを記述していて、 |
|
3988 推奨されないコードを無視したい場合に便利です。 |
|
3989 .TP |
|
3990 .B \-nodeprecatedlist |
|
3991 推奨されない API のリストを含む |
|
3992 ファイル (\f3deprecated-list.html\f1) の生成を禁止 |
|
3993 します。また、このページへのリンクを |
|
3994 ナビゲーションバーに生成することを禁止します。 |
|
3995 ただし、ドキュメントのほかの部分では、 |
|
3996 推奨されない API の生成を続行します。この |
|
3997 オプションは、推奨されない API がソースコードに |
|
3998 含まれておらず、ナビゲーションバーを |
|
3999 すっきりと見せたい場合に便利です。 |
|
4000 .TP |
|
4001 .B \-nosince |
|
4002 生成されるドキュメントから、 |
|
4003 .BR @since |
|
4004 タグに関連した「Since」セクションを削除します。 |
|
4005 .TP |
|
4006 .B \-notree |
|
4007 生成されるドキュメントからクラスおよびインタフェース |
|
4008 階層を省略します。これらのページには、ナビゲーションバーの「ツリー」ボタンからアクセスできます。 |
|
4009 デフォルトでは、階層が作成されます。 |
|
4010 .TP |
|
4011 .B \-noindex |
|
4012 生成されるドキュメントから索引を省略します。 |
|
4013 デフォルトでは、 |
|
4014 索引が作成されます。 |
|
4015 .TP |
|
4016 .B \-nohelp |
|
4017 各出力ページの最上部と最下部の |
|
4018 ナビゲーションバーから [ヘルプ] リンクを |
|
4019 省略します。 |
|
4020 .TP |
|
4021 .B \-nonavbar |
|
4022 生成されるページの最上部と最下部に表示される |
|
4023 ナビゲーションバー、ヘッダ、 |
|
4024 およびフッタの生成を禁止します。 |
|
4025 このオプションは、bottom オプションには影響しません。 |
|
4026 .B \-nonavbar |
|
4027 オプションは、印刷するためだけに |
|
4028 ファイルを PostScript または PDF に変換する |
|
4029 場合など、内容だけが重要でナビゲーションの |
|
4030 必要性がない場合に便利です。 |
|
4031 .TP |
|
4032 .BI \-helpfile " path/filename" |
|
4033 上部と下部のナビゲーションバーの [ヘルプ] リンクの |
|
4034 リンク先となる代替ヘルプファイル |
|
4035 .I path/filename |
|
4036 のパスを指定します。このオプションが指定されていない場合、 |
|
4037 .B javadoc |
|
4038 は、javadoc にハードコードされているヘルプファイル |
|
4039 .B help-doc.html |
|
4040 を自動的に作成します。このオプションを使えば、 |
|
4041 デフォルトの設定をオーバーライドでき |
|
4042 ます。ファイル名にはどのような |
|
4043 名前も指定でき、\f3help-doc.html\f1 には限定されま |
|
4044 せん。 |
|
4045 .B javadoc |
|
4046 は、それに従って、ナビゲーションバーにある |
|
4047 リンクに調整を加えます。 |
|
4048 次に例を示します。 |
|
4049 .LP |
|
4050 .RS |
|
4051 .RS |
|
4052 .ft 3 |
|
4053 .nf |
|
4054 % javadoc \-helpfile /home/doc/myhelp.html java.awt |
|
4055 .fi |
|
4056 .RE |
|
4057 .RE |
|
4058 .ft 1 |
|
4059 .TP |
|
4060 .BI \-stylesheetfile " path/filename" |
|
4061 代替 HTML スタイルシートファイルのパスを指定します。 |
|
4062 このオプションが指定されてい |
|
4063 ない場合、 |
|
4064 .B javadoc |
|
4065 ツールは、内部的にハードコードされている |
|
4066 スタイルシートファイル |
|
4067 .BR stylesheet.css |
|
4068 を自動的に作成します。このオプションを使えば、 |
|
4069 デフォルトの設定をオーバーライドできます。 |
|
4070 filename にはどんなファイル名でも指定でき、 |
|
4071 .BR stylesheet.css |
|
4072 には限定されません。 |
|
4073 次に例を示します。 |
|
4074 .LP |
|
4075 .RS |
|
4076 .RS |
|
4077 .ft 3 |
|
4078 .nf |
|
4079 % javadoc \-stylesheetfile /home/user/mystylesheet.css com.mypackage |
|
4080 .fi |
|
4081 .ft 1 |
|
4082 .RE |
|
4083 .RE |
|
4084 .TP |
|
4085 .B \-serialwarn |
|
4086 .B @serial |
|
4087 タグがない場合、コンパイル時に警告を生成します。デフォルトでは、 |
|
4088 .B javadoc |
|
4089 1.2.2 (およびそれ以降) は |
|
4090 .B @serial |
|
4091 の警告を生成しません。 |
|
4092 (これは、以前のバージョンとは逆です。) |
|
4093 .B @serial |
|
4094 の警告を生成するには、 |
|
4095 このオプションを使用してください。このオプションは、デフォルトの |
|
4096 直列化可能なフィールドと writeExternal メソッドを正しく |
|
4097 ドキュメント化するのに役立ちます。 |
|
4098 .TP |
|
4099 .BI \-charset " name" |
|
4100 このドキュメント用の HTML 文字セットを指定します。この名前は、 |
|
4101 .na |
|
4102 \f2IANA Registry\fP |
|
4103 .fi |
|
4104 (http://www.iana.org/assignments/character\-sets) で与えられた、推奨される MIME 名でなければなりません。次に例を示します。 |
|
4105 .nf |
|
4106 \f3 |
|
4107 .fl |
|
4108 % \fP\f3javadoc \-charset "iso\-8859\-1" mypackage\fP |
|
4109 .fl |
|
4110 .fi |
|
4111 生成されるすべてのページの先頭に、次の行が挿入されます。 |
|
4112 .nf |
|
4113 \f3 |
|
4114 .fl |
|
4115 <META http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1"> |
|
4116 .fl |
|
4117 \fP |
|
4118 .fi |
|
4119 この META タグについては、 |
|
4120 .fi |
|
4121 http://www.w3.org/TR/REC\-html40/charset.html#h\-5.2.2 |
|
4122 の |
|
4123 .na |
|
4124 \f2HTML の標準\fP (4197265 および 4137321) を参照してください。 |
|
4125 .LP |
|
4126 \-encoding と \-docencoding も参照してください。 |
|
4127 .LP |
|
4128 .TP 3 |
|
4129 \-docencoding\ name |
|
4130 生成される HTML ファイルのエンコーディングを指定します。この名前は、 |
|
4131 .na |
|
4132 \f2IANA Registry\fP |
|
4133 .fi |
|
4134 (http://www.iana.org/assignments/character\-sets) で与えられた、推奨される MIME 名でなければなりません。このオプションを省略しながら \-encoding を使用した場合、生成される HTML ファイルのエンコードは、\-encoding によって決められます。次に例を示します。 |
|
4135 .nf |
|
4136 \f3 |
|
4137 .fl |
|
4138 % \fP\f3javadoc \-docencoding "ISO\-8859\-1" mypackage\fP |
|
4139 .fl |
|
4140 .fi |
|
4141 \-encoding および \-charset も参照してください。 |
|
4142 .LP |
|
4143 .TP 3 |
|
4144 \-keywords |
|
4145 HTML メタキーワードタグを、クラスごとに生成されるファイルに追加します。これらのタグは、メタタグを検索するサーチエンジンがページを見つける場合に役立ちます。インターネット全体を検索する多くのサーチエンジンは、ページがメタタグを誤用しているため、メタタグを調べません。一方、検索を自身の Web サイトに限定している企業では、サーチエンジンがメタタグを調べることによってメリットを得られます。 |
|
4146 .LP |
|
4147 メタタグには、クラスの完全修飾名と、フィールドおよびメソッドの修飾されていない名前が含まれます。コンストラクタは、クラス名と同じであるため含まれません。たとえば、クラス String は次のキーワードで開始します。 |
|
4148 .nf |
|
4149 \f3 |
|
4150 .fl |
|
4151 <META NAME="keywords" CONTENT="java.lang.String class"> |
|
4152 .fl |
|
4153 <META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER"> |
|
4154 .fl |
|
4155 <META NAME="keywords" CONTENT="length()"> |
|
4156 .fl |
|
4157 <META NAME="keywords" CONTENT="charAt()"> |
|
4158 .fl |
|
4159 \fP |
|
4160 .fi |
|
4161 .LP |
|
4162 .TP 3 |
|
4163 \-tag\ \ tagname:Xaoptcmf:"taghead" |
|
4164 Javadoc ツールがドキュメンテーションコメント内の引数を 1 つ取る単純なカスタムブロックタグ \f2@\fP\f2tagname\fP を解釈できるようにします。これにより、Javadoc ツールはタグ名の「スペルチェック」を行うことができるので、ソースコード内のすべてのカスタムタグに \f2\-tag\fP オプションを組み込むことをお勧めします。今回の実行で出力されないタグは、\f2X\fP を付けて無効にします。 |
|
4165 .LP |
|
4166 コロン (\f4:\fP) は常に区切り文字になります。\f2tagname\fP でコロンを使用するには、「タグ名でのコロンの使用」を参照してください。 |
|
4167 .LP |
|
4168 \f2\-tag\fP オプションは、タグの見出し「\f2taghead\fP」を太字で出力します。その次の行には、このオプションの引数で指定したテキストが続きます。以下の例を参照してください。ブロックタグと同様、この引数のテキストにはインラインタグを含めることができます。このインラインタグも解釈されます。出力は、引数を 1 つ取る標準のタグ (\f2@return\fP、\f2@author\fP など) の出力とよく似ています。\f2taghead\fP を省略すると、\f2tagname\fP が見出しとして表示されます。 |
|
4169 .LP |
|
4170 \f3タグの配置\fP \- 引数の \f4Xaoptcmf\fP 部分は、ソースコード内のタグを配置できる位置と、\f2X\fP を使ってこのタグを無効にできるかどうかを特定します。タグの配置位置を制限しない場合は \f4a\fP を指定します。それ以外の文字の組み合わせも可能です。 |
|
4171 .br |
|
4172 \f4X\fP (タグの無効化) |
|
4173 .br |
|
4174 \f4a\fP (すべての位置) |
|
4175 .br |
|
4176 \f4o\fP (概要) |
|
4177 .br |
|
4178 \f4p\fP (パッケージ) |
|
4179 .br |
|
4180 \f4t\fP (型すなわちクラスおよびインタフェース) |
|
4181 .br |
|
4182 \f4c\fP (コンストラクタ) |
|
4183 .br |
|
4184 \f4m\fP (メソッド) |
|
4185 .br |
|
4186 \f4f\fP (フィールド) |
|
4187 .LP |
|
4188 シングルタグの例 - |
|
4189 ソースコードの任意の場所で使用できる |
|
4190 タグのタグオプションの例を示します。 |
|
4191 .LP |
|
4192 .RS |
|
4193 .TP 3 |
|
4194 \-tag todo:a:"To Do:" |
|
4195 .RE |
|
4196 .LP |
|
4197 コンストラクタ、メソッド、およびフィールドだけで @todo を |
|
4198 使用させるには、次のようにします。 |
|
4199 .LP |
|
4200 .RS |
|
4201 .ft 3 |
|
4202 .nf |
|
4203 \-tag todo:cmf:"To Do:" |
|
4204 .fi |
|
4205 .ft 1 |
|
4206 .RE |
|
4207 .LP |
|
4208 上記では、末尾のコロン (:) がパラメータの |
|
4209 区切り記号ではなく、表示のとおり、 |
|
4210 見出しテキストの一部であることに注意してください。 |
|
4211 次のように、@todo タグを含むソースコードに |
|
4212 どちらかのタグオプションを使用します。 |
|
4213 .LP |
|
4214 .RS |
|
4215 .ft 3 |
|
4216 .nf |
|
4217 @todo The documentation for this method needs work. |
|
4218 .fi |
|
4219 .ft 1 |
|
4220 .LP |
|
4221 タグ名にコロンを使用する \- |
|
4222 コロン (:) をバックスラッシュでエスケープすると、 |
|
4223 コロンをタグ名に使用することができます。 |
|
4224 .LP |
|
4225 .RS 5 |
|
4226 .nf |
|
4227 /** |
|
4228 * @ejb:bean |
|
4229 */ |
|
4230 .RE |
|
4231 .fi |
|
4232 .LP |
|
4233 でこのタグオプションを使用すると、 |
|
4234 .LP |
|
4235 .RS 5 |
|
4236 .nf |
|
4237 \-tag ejb\\:bean:a:"EJB Bean:" |
|
4238 .RE |
|
4239 .LP |
|
4240 となります。 |
|
4241 .fi |
|
4242 .ft 1 |
|
4243 .RE |
|
4244 .LP |
|
4245 タグ名のスペルチェック (タグの無効化) - 開発者は、ソースコードの中で出力できないカスタムタグを使用することがあります。その場合、ソースタグに存在するすべてのタグをリストし、出力するタグを有効化し、出力しないタグを無効化することが重要です。 X を使用するとタグを無効化でき、これがない場合はタグが有効となります。 この文字の存在によって、 |
|
4246 .B Javadoc |
|
4247 ツールは、検出したタグが未知のタグで、おそらく綴り間違いであると判断できます。 この場合、警告メッセージが表示されます。 |
|
4248 .LP |
|
4249 すでに存在する、配置を指定する引数の値に X を追加した場合、タグを有効にしたいときに X を削除できます。 たとえば、@todo が出力したくないタグの場合、次のようにします。 |
|
4250 .LP |
|
4251 .RS |
|
4252 .ft 3 |
|
4253 .nf |
|
4254 \-tag todo:Xcmf:"To Do:" |
|
4255 .fi |
|
4256 .ft 1 |
|
4257 .RE |
|
4258 .LP |
|
4259 または、次のようにより簡単にすることもできます。 |
|
4260 .LP |
|
4261 .RS |
|
4262 .ft 3 |
|
4263 .nf |
|
4264 \-tag todo:X |
|
4265 .fi |
|
4266 .ft 1 |
|
4267 .RE |
|
4268 .LP |
|
4269 \-tag todo:X の構文は、@todo がタグレットで |
|
4270 定義されている場合も有効です。 |
|
4271 .LP |
|
4272 タグの順序 - |
|
4273 \-tag (および \-taglet) オプションの順序に従って |
|
4274 タグが出力されます。 カスタムタグと標準タグを |
|
4275 混在させることができます。 標準タグのタグオプションは、 |
|
4276 順序を決定するためだけのプレースホルダです。 |
|
4277 これらは標準タグ名だけを使用します |
|
4278 (標準タグの小見出しは変更できません)。 |
|
4279 これを次の例に示します。 |
|
4280 .LP |
|
4281 \-tag がない場合、\-taglet の場所によってその順序が決まります。 |
|
4282 この 2 つが両方ある場合は、コマンド行の最後に使用された方が |
|
4283 順序を決定します (これは、タグとタグレットが、 |
|
4284 コマンド行で使用された順に処理されるためです)。 |
|
4285 たとえば、\-taglet と \-tag が両方とも todo という |
|
4286 名前である場合、コマンド行の最後で使用された |
|
4287 方が順序を決定します。 |
|
4288 .LP |
|
4289 タグの完全なセットの例 - |
|
4290 この例では、出力の Parameters と Throws の間に |
|
4291 To Do を挿入します。 「X」を使用して、@example が |
|
4292 ソースコード内の今回の実行で出力されないタグで |
|
4293 あることを指定できます。 @argfile を使用すると、 |
|
4294 次のように行の継続文字なしで、 |
|
4295 引数ファイルの異なる行にタグを配置できます。 |
|
4296 .LP |
|
4297 .RS |
|
4298 .ft 3 |
|
4299 .nf |
|
4300 \-tag param |
|
4301 \-tag return |
|
4302 \-tag todo:a:"To Do:" |
|
4303 \-tag throws |
|
4304 \-tag see |
|
4305 \-tag example:X |
|
4306 .fi |
|
4307 .ft 1 |
|
4308 .RE |
|
4309 .LP |
|
4310 javadoc がドキュメンテーションコメントを解析する際に、 |
|
4311 検出されたタグのうち、標準タグでもなく、 |
|
4312 \-tag や \-taglet で渡されるタグでもないものは、 |
|
4313 不明なタグとして認識し、警告がスローされます。 |
|
4314 .LP |
|
4315 標準タグは、最初、デフォルトの順序で |
|
4316 リスト内部的に格納されます。 |
|
4317 \-tag オプションを使用すると、このタグがリストに追加されます。 |
|
4318 標準タグはデフォルトの位置から移動します。 |
|
4319 そのため、標準タグで \-tag オプションが省略されると、 |
|
4320 デフォルトの位置に配置されたままになります。 |
|
4321 .LP |
|
4322 競合の回避 - |
|
4323 固有のネームスペースを細かく分けるには、 |
|
4324 パッケージに使用されている com.mycompany.todo |
|
4325 という名前のように、ドット (.) を区切り記号とする名前を使います。 |
|
4326 Sun は今後もドットを含まない標準タグを作成します。 |
|
4327 ユーザが作成したタグは、Sun が定義した同じ |
|
4328 名前のタグの動作をオーバーライドします。 |
|
4329 つまり、ユーザが @todo という名前のタグまたは |
|
4330 タグレットを作成していた場合、そのあとで Sun が |
|
4331 同じ名前の標準タグを作成しても、ユーザが定義した |
|
4332 動作はそのまま維持されます。 |
|
4333 .LP |
|
4334 \f3注釈 vs. Javadoc タグ\fP \- 一般に、追加する必要のあるマークアップが、ドキュメンテーションに影響を与えたりドキュメンテーションを生成したりするためのものである場合、そのマークアップは javadoc タグにすべきです。それ以外の場合は注釈にすべきです。 |
|
4335 .na |
|
4336 「\f2Comparing Annotations and Javadoc Tags\fP」 |
|
4337 .fi |
|
4338 (http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#annotations) を参照してください。 |
|
4339 .LP |
|
4340 \-taglet オプションを使用して、より複雑な |
|
4341 スタンドアロンタグやカスタムインラインタグを |
|
4342 作成することができます。 |
|
4343 .TP |
|
4344 \-taglet class |
|
4345 タグのドキュメントの生成に使うタグレットを起動するための |
|
4346 クラスファイルを指定します。 |
|
4347 クラスの完全修飾名を指定してください。 |
|
4348 このタグレットは、カスタムタグが持っているテキスト引数の |
|
4349 数も定義します。 タグレットはこれらの引数を受け取り、 |
|
4350 処理し、出力を生成します。 タグレットの例の詳細については、 |
|
4351 タグレットの概要を参照してください。 |
|
4352 .LP |
|
4353 タグレットはスタンドアロンタグまたはインラインタグに |
|
4354 使用すると便利です。 タグレットでは任意の |
|
4355 数の引数を持つことができ、カスタムの動作を実装できます。 |
|
4356 たとえば、テキストを太字にしたり、箇条書き形式にしたり、 |
|
4357 テキストをファイルに書き出したり、 |
|
4358 他のプロセスを起動したりすることができるのです。 |
|
4359 .LP |
|
4360 タグレットで指定できるのは、タグの配置場所と配置形式のみです。その他のすべての決定は、ドックレットによって行われます。タグレットを使用しても、包含クラスのリストからクラス名を削除するなどの処理は実行できません。ただし、タグのテキストをファイルに出力したり、別のプロセスをトリガするなどの副作用は得られます。 |
|
4361 .LP |
|
4362 タグレットへのパスを指定するには、 |
|
4363 .B \-tagletpath |
|
4364 オプションを使用します。 |
|
4365 生成されたページの Parameters と Throws の間に |
|
4366 To Do タグレットを挿入する例を示します。 |
|
4367 .LP |
|
4368 .RS |
|
4369 .ft 3 |
|
4370 .nf |
|
4371 \-taglet com.sun.tools.doclets.ToDoTaglet |
|
4372 \-tagletpath /home/taglets |
|
4373 \-tag return |
|
4374 \-tag param |
|
4375 \-tag todo |
|
4376 \-tag throws |
|
4377 \-tag see |
|
4378 .fi |
|
4379 .ft 1 |
|
4380 .RE |
|
4381 .LP |
|
4382 .B \-taglet |
|
4383 オプションを |
|
4384 .B \-tag |
|
4385 オプションの代わりに使用することもできますが、 |
|
4386 その結果、読みにくくなります。 |
|
4387 .TP |
|
4388 \-tagletpath tagletpathlist |
|
4389 taglet クラスファイル (.class) を探すための検索パスを指定します。 |
|
4390 .I tagletpathlist |
|
4391 には、コロン (:) で |
|
4392 区切って複数のパスを含めることができます。 |
|
4393 .B Javadoc |
|
4394 ツールは、指定されたパス以下のすべての |
|
4395 サブディレクトリを検索します。 |
|
4396 .TP |
|
4397 \-docfilessubdirs |
|
4398 doc-files ディレクトリを、下の階層を含めてコピー |
|
4399 できるようにします。 つまり、サブディレクトリとすべての |
|
4400 コンテンツが、生成先ディレクトリに再帰的にコピーされます。 |
|
4401 たとえば、 |
|
4402 .BR doc-files/example/images |
|
4403 ディレクトリとその中のファイルがコピーされます。 |
|
4404 サブディレクトリを除外するためのオプションもあります。 |
|
4405 .TP |
|
4406 \-excludedocfilessubdirs name1:name2:... |
|
4407 doc-files のサブディレクトリで、指定された |
|
4408 名前のものを除外します。 このオプションを使用すると、 |
|
4409 SCCS およびその他のソースコード管理の |
|
4410 サブディレクトリをコピーしないようにできます。 |
|
4411 .TP |
|
4412 \-noqualifier all | packagename1:packagename2:... |
|
4413 修飾パッケージ名を、出力のクラス名の前から削除します。 |
|
4414 \-noqualifier の引数は |
|
4415 all (すべてのパッケージ修飾子を削除)、 |
|
4416 またはコロンで区切られたパッケージリストの |
|
4417 いずれかで、修飾子として削除されます。 |
|
4418 ワイルドカードも使用できます。 |
|
4419 パッケージ名はクラス名またはインタフェース名が |
|
4420 表示されたところから削除されます。 |
|
4421 .LP |
|
4422 次の例では、すべてのパッケージ修飾子を省略します。 |
|
4423 .LP |
|
4424 .RS |
|
4425 .ft 3 |
|
4426 .nf |
|
4427 \-noqualifier all |
|
4428 .fi |
|
4429 .ft 1 |
|
4430 .RE |
|
4431 .LP |
|
4432 次の例では、パッケージ修飾子 java.lang |
|
4433 および java.io を省略します。 |
|
4434 .LP |
|
4435 .RS |
|
4436 .ft 3 |
|
4437 .nf |
|
4438 \-noqualifier java.lang:java.io |
|
4439 .fi |
|
4440 .ft 1 |
|
4441 .RE |
|
4442 .LP |
|
4443 次の例では、java および com.sun から |
|
4444 始まる (javax を除く) |
|
4445 サブパッケージのパッケージ修飾子を削除します。 |
|
4446 .LP |
|
4447 .RS |
|
4448 .ft 3 |
|
4449 .nf |
|
4450 \-noqualifier java.*:com.sun.* |
|
4451 .fi |
|
4452 .ft 1 |
|
4453 .RE |
|
4454 .LP |
|
4455 パッケージ修飾子が上記の動作に従って表示される場合、名前は適切に短くされます。詳細は「名前の表示方法」を参照してください。この規則は、 |
|
4456 \-noqualifier が |
|
4457 使用されているかどうかにかかわらず存在します。 |
|
4458 .TP |
|
4459 .BI \-notimestamp |
|
4460 タイムスタンプが抑制されます。 |
|
4461 各ページ先頭近くにある、生成された HTML 内の |
|
4462 HTML コメントでタイムスタンプが隠されます。 |
|
4463 .B Javadoc |
|
4464 を 2 つのソースベースで実行し、それらに対して |
|
4465 diff を実行するときにこのオプションを使用すると、 |
|
4466 タイムスタンプによって diff が発生しなくなるので |
|
4467 便利です (このオプションを使用しないと、 |
|
4468 各ページで diff になります)。 |
|
4469 タイムスタンプには |
|
4470 .B Javadoc |
|
4471 のバージョン番号が含まれており、 |
|
4472 次のようになります。 |
|
4473 .LP |
|
4474 .RS 5 |
|
4475 <!-- Generated by javadoc (build 1.5.0-internal) |
|
4476 on Tue Jun 22 09:57:24 PDT 2004 --> |
|
4477 .RE |
|
4478 .TP |
|
4479 \-nocomment |
|
4480 記述およびすべてのタグを含むコメント |
|
4481 本文全体を抑制し、宣言だけを生成します。 |
|
4482 このオプションにより、元は異なる目的のためだった |
|
4483 ソースファイルを再利用し、 |
|
4484 新しいプロジェクトのためのスケルトンを |
|
4485 作成できるようになりました。 |
|
4486 .SS コマンド行引数ファイル |
|
4487 .BR javadoc |
|
4488 のコマンド行を短くしたり簡潔にしたりするために、 |
|
4489 .BR javadoc |
|
4490 コマンドに対する引数 (\-J オプションを除く) が |
|
4491 入った 1 つ以上のファイルを指定することができます。 |
|
4492 このことを利用すれば、どのオペレーティングシステム |
|
4493 上でも、任意の長さの |
|
4494 .BR javadoc |
|
4495 コマンドを作成できます。 |
|
4496 .LP |
|
4497 引数ファイルには、javac オプションとソースファイル名を |
|
4498 自由に組み合わせて記述できます。 |
|
4499 また、Javadoc オプションに対する引数だけを記述してもかまいません。 |
|
4500 ファイル内の各引数は、空白文字または改行で区切ります。 |
|
4501 ファイル名に空白が含まれている場合は、そのファイル名全体を二重引用符で囲む必要があります。 |
|
4502 .LP |
|
4503 .LP |
|
4504 引数ファイル内のファイル名は、 |
|
4505 現在のディレクトリから見た相対パスになります。 |
|
4506 引数ファイルの位置から見た相対パスではありません。 |
|
4507 引数ファイル内のファイル名リストでは、 |
|
4508 ワイルドカード (*) は使用できません。 |
|
4509 たとえば、*.java とは指定できません。 |
|
4510 引数ファイル内の引数で @ 文字を使用して、 |
|
4511 複数のファイルを再帰的に解釈することはサポートされていません。 |
|
4512 また、\-J オプションもサポートされていません。 |
|
4513 このオプションは起動ツールに渡されますが、 |
|
4514 起動ツールでは引数ファイルをサポートしていないからです。 |
|
4515 .LP |
|
4516 .BR javadoc |
|
4517 を実行するときに、各引数ファイルのパスとファイル名の |
|
4518 先頭に @ 文字を付けて渡します。 |
|
4519 .BR javadoc |
|
4520 は、@ 文字で始まる引数を見つけると、 |
|
4521 そのファイルの内容を展開して引数リストに挿入します。 |
|
4522 .LP |
|
4523 引数ファイルを 1 つ指定する例 |
|
4524 .LP |
|
4525 argfile という名前の引数ファイルにすべての |
|
4526 Javadoc 引数を格納し、次のように使用することができます。 |
|
4527 .LP |
|
4528 .RS |
|
4529 .ft 3 |
|
4530 .nf |
|
4531 % javadoc @argfile |
|
4532 .fi |
|
4533 .ft 1 |
|
4534 .RE |
|
4535 .LP |
|
4536 この引数ファイルには、次の例で示されている |
|
4537 2 つのファイルの内容を両方とも入れることができます。 |
|
4538 .LP |
|
4539 引数ファイルを 2 つ指定する例 |
|
4540 .LP |
|
4541 Javadoc オプション用に 1 つ、パッケージ名またはソースファイル名用に |
|
4542 1 つというように、2 つの引数ファイルを作成し、 |
|
4543 次のようにして使用することができます。 |
|
4544 なお、このあとのリストでは、行の継続文字を使用していません。 |
|
4545 .LP |
|
4546 以下の内容を含む options という名前のファイルを作成します。 |
|
4547 .LP |
|
4548 .RS |
|
4549 .ft 3 |
|
4550 .nf |
|
4551 \-d docs-filelist |
|
4552 \-use |
|
4553 \-splitindex |
|
4554 \-windowtitle 'Java 2 Platform v1.3 API Specification' |
|
4555 \-doctitle 'Java<sup><font size="-2">TM</font></sup> 2\\ |
|
4556 Platform 5.0 API Specification' |
|
4557 \-header '<b>Java 2 Platform </b><br><font size="-1">5.0</font>' |
|
4558 \-bottom 'Copyright 1993-2000 Sun Microsystems, Inc. All Rights Reserved.' |
|
4559 \-group "Core Packages" "java.*" |
|
4560 \-overview /java/pubs/ws/1.5/src/share/classes/overview-core.html |
|
4561 \-sourcepath /java/pubs/ws/1.5/src/share/classes |
|
4562 .fi |
|
4563 .ft 1 |
|
4564 .RE |
|
4565 .LP |
|
4566 以下の内容を含む packages という名前のファイルを作成します。 |
|
4567 .LP |
|
4568 .RS |
|
4569 .ft 3 |
|
4570 .nf |
|
4571 com.mypackage1 |
|
4572 com.mypackage2 |
|
4573 com.mypackage3 |
|
4574 .fi |
|
4575 .ft 1 |
|
4576 .RE |
|
4577 .LP |
|
4578 そのあと、次のコマンドを使用して javadoc を実行します。 |
|
4579 .LP |
|
4580 .RS |
|
4581 .ft 3 |
|
4582 .nf |
|
4583 % javadoc @options @packages |
|
4584 .fi |
|
4585 .ft 1 |
|
4586 .RE |
|
4587 .LP |
|
4588 パス付きの引数ファイルの例 |
|
4589 .LP |
|
4590 引数ファイルには、パスを指定できます。 |
|
4591 ただし、そのファイル内に指定されたファイル名は、 |
|
4592 現在の作業ディレクトリから見た相対パスになります。 |
|
4593 つまり、下の例の場合は、path1 や |
|
4594 path2 から見た相対パスではありません。 |
|
4595 .LP |
|
4596 .RS |
|
4597 .ft 3 |
|
4598 .nf |
|
4599 % javadoc @path1/options @path2/packages |
|
4600 .fi |
|
4601 .ft 1 |
|
4602 .RE |
|
4603 .LP |
|
4604 オプションの引数の例 |
|
4605 .LP |
|
4606 次に、javadoc オプションに対する引数だけを引数ファイルに |
|
4607 格納する例を示します。 ここでは、\-bottom オプションを |
|
4608 例に取り上げます。そのオプションには、 |
|
4609 かなり長い引数を指定することがあるからです。 |
|
4610 まず、このオプションのテキスト引数になる |
|
4611 次のような内容を含む、bottom という名前の |
|
4612 ファイルを作成します。 |
|
4613 .LP |
|
4614 '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi"> |
|
4615 Submit a bug or feature</a><br><br>Java is a |
|
4616 trademark or registered trademark of |
|
4617 Sun Microsystems, Inc. in the US and other |
|
4618 countries.<br>Copyright 1993-2000 Sun |
|
4619 Microsystems, Inc. 901 San Antonio Road,<br>Palo |
|
4620 Alto, California, 94303, U.S.A. |
|
4621 All Rights Reserved.</font>' |
|
4622 .LP |
|
4623 そのあと、次のようにして |
|
4624 .B javadoc |
|
4625 ツールを実行します。 |
|
4626 .LP |
|
4627 .TP 3 |
|
4628 % javadoc \-bottom @bottom @packages |
|
4629 .LP |
|
4630 また、引数ファイルの先頭に |
|
4631 \-bottom オプションを組み込んでおけば、次のようにして実行できます。 |
|
4632 .LP |
|
4633 .RS |
|
4634 .ft 3 |
|
4635 .nf |
|
4636 % javadoc @bottom @packages |
|
4637 .fi |
|
4638 .ft 1 |
|
4639 .RE |
|
4640 .TP |
|
4641 .SH 実行 |
|
4642 .SS Javadoc の実行 |
|
4643 バージョン番号 - |
|
4644 .LP |
|
4645 javadoc のバージョン番号は |
|
4646 .BR javadoc \-J\-version |
|
4647 を使用することで確認できます。 |
|
4648 標準ドックレットのバージョン番号は出力ストリームに |
|
4649 表示されます。 |
|
4650 これは \-quiet オプションでオフにできます。 |
|
4651 .LP |
|
4652 プログラムから利用できる public インタフェース - |
|
4653 Java 言語で書かれたプログラム内から |
|
4654 .B javadoc |
|
4655 ツールを呼び出します。 |
|
4656 このインタフェースは |
|
4657 .BR com.sun.tools.javadoc.Main |
|
4658 (javadoc は再入) |
|
4659 にあります。 詳細は、「標準ドックレット」 |
|
4660 を参照してください。 |
|
4661 .LP |
|
4662 \f3ドックレットの実行\fP \- |
|
4663 下記の説明は、標準 HTML ドックレットを呼び出すためのものです。カスタムドックレットを呼び出すには、\-doclet および \-docletpath オプションを使用します。特定のドックレットを実行した完全な例については、 |
|
4664 .na |
|
4665 「\f2Running the MIF Doclet\fP」 |
|
4666 .fi |
|
4667 (http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet) を参照してください。 |
|
4668 .LP |
|
4669 .SH "使用例" |
|
4670 .B javadoc |
|
4671 は、パッケージ全体に対して実行することも、 |
|
4672 個々のソースファイルに対して実行することも |
|
4673 できます。各パッケージ名は、それぞれの |
|
4674 パッケージ名に対応するディレクトリ名を |
|
4675 持ちます。次の例では、ソースファイルは |
|
4676 .BR /home/src/java/awt/*java |
|
4677 にあります。生成先ディレクトリは |
|
4678 .BR /home/html |
|
4679 です。 |
|
4680 .SS "1 つ以上のパッケージのドキュメント化" |
|
4681 パッケージをドキュメント化するには、その |
|
4682 パッケージのソースファイル (*\f3.java\f1) |
|
4683 が、パッケージと同じ名前を持つディレクトリ |
|
4684 内に存在していなければなりません。 |
|
4685 パッケージ名が複数の識別子で構成されている |
|
4686 (java.awt.color のように、各識別子はドットで |
|
4687 区切られている) 場合は、後続の各識別子が下位の |
|
4688 サブディレクトリに対応して |
|
4689 いなければなりません (java/awt/color など)。 |
|
4690 1 つのパッケージのための複数のソースファイルを、 |
|
4691 異なる場所にある 2 つのディレクトリツリーに分けて |
|
4692 格納することも可能です |
|
4693 ( |
|
4694 .BR src1/java/awt/color |
|
4695 と |
|
4696 .BR src2/java/awt/color |
|
4697 など)。 |
|
4698 ただし、その場合は、\-sourcepath によって、 |
|
4699 その両方の場所を指定しなければなりません。 |
|
4700 .LP |
|
4701 .B javadoc |
|
4702 を実行するには、cd コマンドを使って |
|
4703 ディレクトリを変更するか、 |
|
4704 または |
|
4705 .B \-sourcepath |
|
4706 オプションを使用します。 |
|
4707 それぞれの例を次に示します。 |
|
4708 .TP 2 |
|
4709 \(bu |
|
4710 .B ケース 1 - 1 つ以上のパッケージからの起動を再帰的に実行 - |
|
4711 この例では javadoc が任意のディレクトリから実行できるように、 |
|
4712 .BR \-sourcepath |
|
4713 を使用し、再帰的処理のために -subpackages (1.4 の新オプション) を使用します。 これは、java のサブパッケージ ( |
|
4714 .BR java.net |
|
4715 および |
|
4716 .BR java.lang |
|
4717 をルートとするパッケージを除く) を処理します。 |
|
4718 これによって |
|
4719 .BR java.lang.ref ( |
|
4720 .BR java.lang |
|
4721 のサブパッケージ) が |
|
4722 除外されることに注意してください。 |
|
4723 .LP |
|
4724 .RS |
|
4725 .ft 3 |
|
4726 .nf |
|
4727 % javadoc \-d /home/html \-sourcepath /home/src \-subpackages java \-exclude java.net:java.lang |
|
4728 .fi |
|
4729 .ft 1 |
|
4730 .RE |
|
4731 .LP |
|
4732 他のパッケージツリーを処理するには、 |
|
4733 .BR java:javax:org.xml.sax |
|
4734 のように、その名前を |
|
4735 .BR \-subpackages |
|
4736 引数に追加します。 |
|
4737 .TP 2 |
|
4738 \(bu |
|
4739 .B ケース 2 - ルートソースディレクトリに移ってから明示的なパッケージを実行 - |
|
4740 完全修飾パッケージの |
|
4741 親ディレクトリに移動します。 |
|
4742 次に、ドキュメント化する |
|
4743 1 つ以上のパッケージ名を指定して |
|
4744 .BR javadoc |
|
4745 を実行します。 |
|
4746 .LP |
|
4747 .RS |
|
4748 .ft 3 |
|
4749 .nf |
|
4750 % cd /home/src/ |
|
4751 % javadoc \-d /home/html java.awt java.awt.event |
|
4752 .fi |
|
4753 .ft 1 |
|
4754 .RE |
|
4755 .TP 2 |
|
4756 \(bu |
|
4757 .B ケース 3 - 任意のディレクトリから実行。ソースファイルは 1 つのディレクトリツリー内にある - このケースでは、現在のディレクトリがどこであってもかまいません。 トップレベルのパッケージの親ディレクトリを |
|
4758 .B \-sourcepath |
|
4759 に指定し、ドキュメント化する 1 つ以上のパッケージ名を指定して、 |
|
4760 .B javadoc |
|
4761 を実行します。 |
|
4762 .LP |
|
4763 .RS |
|
4764 .ft 3 |
|
4765 .nf |
|
4766 % javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event |
|
4767 .fi |
|
4768 .ft 1 |
|
4769 .RE |
|
4770 .TP 2 |
|
4771 \(bu |
|
4772 .B ケース 4 - 任意のディレクトリから実行。ソースファイルは複数のディレクトリツリー内にある - これはケース 3 と似ていますが、パッケージが複数のディレクトリツリーに存在します。 各ツリーのルートへのパスを |
|
4773 .B \-sourcepath |
|
4774 に指定し (コロンで区切る)、ドキュメント化する 1 つ以上のパッケージ名を指定して、javadoc を実行します。 1 つのパッケージのすべてのソースファイルが、1 つのルートディレクトリの下に存在しなければならない、ということはありません。ソースパスとして指定された場所のどこかで見付かれば十分です。 |
|
4775 .LP |
|
4776 .RS |
|
4777 .ft 3 |
|
4778 .nf |
|
4779 % javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java.awt java.awt.event |
|
4780 .fi |
|
4781 .ft 1 |
|
4782 .RE |
|
4783 .LP |
|
4784 結果: どちらのケースでも、パッケージ |
|
4785 .B java.awt |
|
4786 と |
|
4787 .B java.awt.event |
|
4788 の public および protected |
|
4789 なクラスとインタフェースを対象に、HTML 形式の |
|
4790 ドキュメントが生成され、指定 |
|
4791 された生成先ディレクトリ (\f3/home/html\f1) に HTML ファイルが |
|
4792 保存されます。2 つ |
|
4793 以上のパッケージが生成されるので、ドキュメントは、 |
|
4794 パッケージのリスト、クラスのリスト、 |
|
4795 およびメインページの 3 つのフレームを持つことになります。 |
|
4796 .SS "1 つ以上のクラスのドキュメント化" |
|
4797 .B javadoc |
|
4798 ツールを実行する 2 番目の方法は、1 つ以上のソースファイル ( |
|
4799 .B .java |
|
4800 ) を渡すことです。 |
|
4801 .B javadoc |
|
4802 は、次の 2 つのどちらかの方法で実行できます。 |
|
4803 1 つは、(cd によって) ディレクトリを |
|
4804 変更する方法、もう 1 つは |
|
4805 .B .java |
|
4806 ファイルへのパスを完全指定する方法です。 |
|
4807 相対パスは、現在のディレクトリからの相対パスです。 |
|
4808 ソースファイルを渡した場合、 |
|
4809 .B \-sourcepath |
|
4810 オプションは無視されます。 |
|
4811 アスタリスク (*) の |
|
4812 ようなコマンド行ワイルドカードを使用すると、 |
|
4813 クラスのグループを指定できます。 |
|
4814 .TP 2 |
|
4815 \(bu |
|
4816 .B ケース 1 ソースディレクトリへの移動: |
|
4817 .B .java |
|
4818 ファイルのあるディレクトリに移動します。 |
|
4819 次に、ドキュメント化する 1 つ以上の |
|
4820 ソースファイルの名前を指定して |
|
4821 .BR javadoc |
|
4822 を実行します。 |
|
4823 .LP |
|
4824 .RS |
|
4825 .ft 3 |
|
4826 .nf |
|
4827 % cd /home/src/java/awt |
|
4828 % javadoc \-d /home/html Button.java Canvas.java Graphics*.java |
|
4829 .fi |
|
4830 .ft 1 |
|
4831 .RE |
|
4832 .LP |
|
4833 .RS 2 |
|
4834 この例では、クラス Button と Canvas、 |
|
4835 および先頭が Graphics で始まるクラスの |
|
4836 HTML 形式のドキュメントが生成されます。 |
|
4837 .BR javadoc |
|
4838 の引数として渡されているのは、 |
|
4839 パッケージ名ではなくソースファイルなので、 |
|
4840 ドキュメントは、クラスのリストと |
|
4841 メインページの 2 つのフレームを持つことになります。 |
|
4842 .RE |
|
4843 .TP 2 |
|
4844 \(bu |
|
4845 .B ケース 2 パッケージのルートディレクトリへの移動: |
|
4846 これは、同じルート内にある複数のサブパッケージのソースファイルを個々に |
|
4847 ドキュメント化する場合に便利です。パッケージの |
|
4848 ルートディレクトリに移動し、各ソースファイルを |
|
4849 ルートからのパスで指定します。 |
|
4850 .LP |
|
4851 .RS |
|
4852 .ft 3 |
|
4853 .nf |
|
4854 % cd /home/src/ |
|
4855 % javadoc \-d /home/html java/awt/Button.java java/applet/Applet.java |
|
4856 .fi |
|
4857 .ft 1 |
|
4858 .RE |
|
4859 .LP |
|
4860 .RS 2 |
|
4861 この例では、Button クラスおよび Applet クラス |
|
4862 用の HTML 形式のドキュメント |
|
4863 が生成されます。 |
|
4864 .RE |
|
4865 .TP 2 |
|
4866 \(bu |
|
4867 .B ケース 3 すべてのディレクトリから: |
|
4868 このケースでは、現在のディレクトリがどの |
|
4869 ディレクトリでも問題はありません。 |
|
4870 ドキュメント化する |
|
4871 .B .java |
|
4872 ファイルへの絶対パスまたは |
|
4873 相対パスを指定して |
|
4874 .BR javadoc |
|
4875 を実行します。 |
|
4876 .LP |
|
4877 .RS |
|
4878 .ft 3 |
|
4879 .nf |
|
4880 % javadoc \-d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java |
|
4881 .fi |
|
4882 .ft 1 |
|
4883 .RE |
|
4884 .LP |
|
4885 .RS 2 |
|
4886 この例では、クラス |
|
4887 .B Button |
|
4888 および先頭が |
|
4889 .BR Graphics |
|
4890 で始まるクラスの HTML 形式 |
|
4891 のドキュメントが生成されます。 |
|
4892 .RE |
|
4893 .SS "パッケージとクラスのドキュメント化" |
|
4894 パッケージ全体と個々のクラスを同時にドキュメント |
|
4895 化できます。次に示すのは、上に示 |
|
4896 した 2 つの例を組み合わせた例です。 |
|
4897 .B \-sourcepath |
|
4898 は、パッケージへのパスに対しては使用できますが、 |
|
4899 個々のクラスのパスに対しては使用 |
|
4900 できません。 |
|
4901 .LP |
|
4902 .RS |
|
4903 .ft 3 |
|
4904 .nf |
|
4905 % javadoc \-d /home/html \-sourcepath /home/src java.awt /home/src/java/applet/Applet.java |
|
4906 .fi |
|
4907 .ft 1 |
|
4908 .RE |
|
4909 .LP |
|
4910 この例では、パッケージ |
|
4911 .B java.awt |
|
4912 とクラス |
|
4913 .B Applet |
|
4914 の HTML 形式のドキュメントが |
|
4915 生成されます。 |
|
4916 .B javadoc |
|
4917 は、Applet のパッケージ名を、 |
|
4918 .B Applet.java |
|
4919 ソースファイル内のパッケージの宣言 (宣言がある場合) から決定します。 |
|
4920 .SS "使用例" |
|
4921 .B javadoc |
|
4922 ツールには、多くの便利なオプションがあり、 |
|
4923 その中のいくつかは、ほかのオプションよりもよく |
|
4924 使われます。以下は、makefile 変数を使って Java プラット |
|
4925 フォーム API 上で |
|
4926 .B javadoc |
|
4927 ツールを実行するために使う効果的なコマンドです。 |
|
4928 ここでは 180M バイトのメモリを使用して、 |
|
4929 Java 2 Platform, Standard Edition, v1.2 に |
|
4930 存在する、約 1500 個の public および protected |
|
4931 クラスについてドキュメントを生成します。 |
|
4932 .LP |
|
4933 同じ例を 2 回掲載します。最初の例はコマンド行から実行するもので、2 番目の例は Makefile から実行するものです。 オプションの引数に絶対パスを使用しているため、任意のディレクトリからこの |
|
4934 .B javadoc |
|
4935 コマンドを実行できます。 |
|
4936 .SS コマンド行の例 |
|
4937 次のコマンド行の例は 900 文字を超えているため、 |
|
4938 DOS などのシェルには大きすぎます。 |
|
4939 この制限を回避するには、コマンド行 |
|
4940 引数ファイルを使用します。 |
|
4941 または、シェルスクリプトを記述します。 |
|
4942 .LP |
|
4943 .nf |
|
4944 \f3 |
|
4945 .fl |
|
4946 % javadoc \-sourcepath /java/jdk/src/share/classes \\ |
|
4947 .fl |
|
4948 \-overview /java/jdk/src/share/classes/overview.html \\ |
|
4949 .fl |
|
4950 \-d /java/jdk/build/api \\ |
|
4951 .fl |
|
4952 \-use \\ |
|
4953 .fl |
|
4954 \-splitIndex \\ |
|
4955 .fl |
|
4956 \-windowtitle 'Java 2 Platform 5.0 API Specification' \\ |
|
4957 .fl |
|
4958 \-doctitle 'Java<sup><font size="\-2">TM</font></sup> 2 Platform 5.0 API Specification' \\ |
|
4959 .fl |
|
4960 \-header '<b>Java 2 Platform </b><br><font size="\-1">5.0</font>' \\ |
|
4961 .fl |
|
4962 \-bottom '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit |
|
4963 .fl |
|
4964 a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems, |
|
4965 .fl |
|
4966 Inc. in the US and other countries.<br>Copyright 1993\-1999 Sun Microsystems, Inc. |
|
4967 .fl |
|
4968 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' \\ |
|
4969 .fl |
|
4970 \-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \\ |
|
4971 .fl |
|
4972 \-group "Extension Packages" "javax.*" \\ |
|
4973 .fl |
|
4974 \-J\-Xmx180m \\ |
|
4975 .fl |
|
4976 @packages |
|
4977 .fl |
|
4978 \fP |
|
4979 .fi |
|
4980 |
|
4981 .LP |
|
4982 .LP |
|
4983 上記のコマンドで、packages は、 |
|
4984 処理対象のパッケージ名 ( |
|
4985 .BR java.applett |
|
4986 .BR java.lang など) が |
|
4987 入っているファイルの名前です。 各オプションの、 |
|
4988 単一引用符で囲まれた引数の内側には、 |
|
4989 改行文字を挿入できません。 たとえば、 |
|
4990 この例をコピー＆ペーストする場合は、 |
|
4991 .B \-bottom |
|
4992 オプションから改行文字を削除してください。 |
|
4993 さらに、このあとの「注」も参照してください。 |
|
4994 .SS Makefile の例 |
|
4995 ここでは、GNU Makefile の例を示します。 |
|
4996 Windows の Makefile の例については、 |
|
4997 .na |
|
4998 「\f2creating a makefile for Windows\fP」 |
|
4999 .fi |
|
5000 (http://java.sun.com/j2se/javadoc/faq/index.html#makefiles) を参照してください。 |
|
5001 .LP |
|
5002 .nf |
|
5003 \f3 |
|
5004 .fl |
|
5005 javadoc \-\fP\f3sourcepath\fP\f3 $(SRCDIR) \\ /* Sets path for source files */ |
|
5006 .fl |
|
5007 \-\fP\f3overview\fP\f3 $(SRCDIR)/overview.html \\ /* Sets file for overview text */ |
|
5008 .fl |
|
5009 \-\fP\f3d\fP\f3 /java/jdk/build/api \\ /* Sets destination directory */ |
|
5010 .fl |
|
5011 \-\fP\f3use\fP\f3 \\ /* Adds "Use" files */ |
|
5012 .fl |
|
5013 \-\fP\f3splitIndex\fP\f3 \\ /* Splits index A\-Z */ |
|
5014 .fl |
|
5015 \-\fP\f3windowtitle\fP\f3 $(WINDOWTITLE) \\ /* Adds a window title */ |
|
5016 .fl |
|
5017 \-\fP\f3doctitle\fP\f3 $(DOCTITLE) \\ /* Adds a doc title */ |
|
5018 .fl |
|
5019 \-\fP\f3header\fP\f3 $(HEADER) \\ /* Adds running header text */ |
|
5020 .fl |
|
5021 \-\fP\f3bottom\fP\f3 $(BOTTOM) \\ /* Adds text at bottom */ |
|
5022 .fl |
|
5023 \-\fP\f3group\fP\f3 $(GROUPCORE) \\ /* 1st subhead on overview page */ |
|
5024 .fl |
|
5025 \-\fP\f3group\fP\f3 $(GROUPEXT) \\ /* 2nd subhead on overview page */ |
|
5026 .fl |
|
5027 \-\fP\f3J\fP\f3\-Xmx180m \\ /* Sets memory to 180MB */ |
|
5028 .fl |
|
5029 java.lang java.lang.reflect \\ /* Sets packages to document */ |
|
5030 .fl |
|
5031 java.util java.io java.net \\ |
|
5032 .fl |
|
5033 java.applet |
|
5034 .fl |
|
5035 |
|
5036 .fl |
|
5037 WINDOWTITLE = 'Java 2 Platform v1.2 API Specification' |
|
5038 .fl |
|
5039 DOCTITLE = 'Java<sup><font size="\-2">TM</font></sup> 2 Platform v1.2 API Specification' |
|
5040 .fl |
|
5041 HEADER = '<b>Java 2 Platform </b><br><font size="\-1">v1.2</font>' |
|
5042 .fl |
|
5043 BOTTOM = '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit |
|
5044 .fl |
|
5045 a bug or feature</a><br><br>Java is a trademark or registered trademark |
|
5046 .fl |
|
5047 of Sun Microsystems, Inc. in the US and other countries.<br>Copyright 1993\-1999 |
|
5048 .fl |
|
5049 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. |
|
5050 .fl |
|
5051 All Rights Reserved.</font>' |
|
5052 .fl |
|
5053 GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"' |
|
5054 .fl |
|
5055 GROUPEXT = '"Extension Packages" "javax.*"' |
|
5056 .fl |
|
5057 SRCDIR = '/java/jdk/1.2/src/share/classes' |
|
5058 .fl |
|
5059 \fP |
|
5060 .fi |
|
5061 |
|
5062 .LP |
|
5063 .LP |
|
5064 Makefile の引数は、単一引用符で囲みます。 |
|
5065 .SS 注 |
|
5066 .TP 2 |
|
5067 \(bu |
|
5068 .B \-windowtitle |
|
5069 オプションを省略すると、 |
|
5070 .B Javadoc |
|
5071 ツールによってドキュメントタイトルが |
|
5072 ウィンドウタイトルにコピーされます。 |
|
5073 .B \-windowtitle |
|
5074 のテキストは、基本的に |
|
5075 .B \-doctitle |
|
5076 と同じです。ただし、HTML タグは使用しません。 |
|
5077 HTML タグは、ウィンドウタイトルにそのままの |
|
5078 テキストとして表示されてしまいます。 |
|
5079 .TP 2 |
|
5080 \(bu |
|
5081 この例のように |
|
5082 .B \-footer |
|
5083 オプションを省略すると、 |
|
5084 .B Javadoc |
|
5085 ツールによってヘッダテキストが |
|
5086 フッタにコピーされます。 |
|
5087 .TP 2 |
|
5088 \(bu |
|
5089 この例では必要ありませんが、 |
|
5090 .B \-classpath |
|
5091 および |
|
5092 .BR \-link |
|
5093 も重要なオプションです。 |
|
5094 |
|
5095 .LP |
|
5096 .SH トラブルシューティング |
|
5097 .SS 一般的なトラブルシューティング |
|
5098 .TP 2 |
|
5099 \(bu |
|
5100 Javadoc FAQ - よく問題となるバグや |
|
5101 トラブルシューティングの |
|
5102 ヒントは |
|
5103 .na |
|
5104 「\f2Javadoc FAQ\fP」 |
|
5105 .fi |
|
5106 (http://java.sun.com/j2se/javadoc/faq/index.html#B) にあります。 |
|
5107 .TP 2 |
|
5108 \(bu |
|
5109 バグおよび制限事項 - また、バグの一部は、 |
|
5110 .na |
|
5111 「\f2Important Bug Fixes and Changes\fP」 |
|
5112 .fi |
|
5113 (http://java.sun.com/j2se/1.5.0/fixedbugs/index.html) でも参照できます。 |
|
5114 .TP 2 |
|
5115 \(bu |
|
5116 バージョン番号 - バージョン番号を参照してください。 |
|
5117 .TP 2 |
|
5118 \(bu |
|
5119 有効なクラスだけをドキュメント化 - |
|
5120 javadoc がパッケージをドキュメント化するとき、 |
|
5121 有効なクラス名で構成されているファイルだけを |
|
5122 読み込むようになりました。 |
|
5123 ファイル名にハイフン (-) などを含めることで、 |
|
5124 javadoc がファイルを解析しないようにできます。 |
|
5125 .SS エラーと警告 |
|
5126 エラーメッセージおよび警告メッセージには、 |
|
5127 ファイル名と宣言行に対する行番号が |
|
5128 含まれますが、doc コメントの特定の |
|
5129 行に対する行番号は含まれません。 |
|
5130 .TP 2 |
|
5131 \(bu |
|
5132 "error: cannot read: Class1.java" - |
|
5133 .B Javadoc |
|
5134 ツールは現在のディレクトリの |
|
5135 .BR Class1.java |
|
5136 クラスを読み込もうとしています。 |
|
5137 クラス名は、絶対パスまたは相対パスで表示されます。 |
|
5138 この場合、./Class1.java と同じです。 |
|
5139 .LP |
|
5140 .SH "環境" |
|
5141 .TP 20 |
|
5142 .SB CLASSPATH |
|
5143 環境変数は、 |
|
5144 .B javadoc |
|
5145 がユーザクラスファイルを探すときに使う、パスを指定します。環境変数は、 |
|
5146 .B \-classpath |
|
5147 オプションによってオーバーライドされます。ディレクトリは |
|
5148 コロンで分割します。たとえば、 |
|
5149 次のとおりです。 |
|
5150 .RS 15 |
|
5151 .sp 1n |
|
5152 .B .:/home/classes:/usr/local/java/classes |
|
5153 .RE |
|
5154 .br |
|
5155 .ne 11 |
|
5156 .SH "関連項目" |
|
5157 .LP |
|
5158 .RS 3 |
|
5159 .TP 2 |
|
5160 o |
|
5161 javac |
|
5162 .TP 2 |
|
5163 o |
|
5164 java |
|
5165 .TP 2 |
|
5166 o |
|
5167 jdb |
|
5168 .TP 2 |
|
5169 o |
|
5170 javah |
|
5171 .TP 2 |
|
5172 o |
|
5173 javap |
|
5174 .TP 2 |
|
5175 o |
|
5176 .fi |
|
5177 http://java.sun.com/j2se/javadoc/index.jsp |
|
5178 の |
|
5179 .na |
|
5180 「\f2Javadoc Home Page\fP」 |
|
5181 .TP 2 |
|
5182 o |
|
5183 .fi |
|
5184 http://java.sun.com/j2se/javadoc/writingdoccomments/index.html |
|
5185 の |
|
5186 .na |
|
5187 「\f2How to Write Doc Comments for Javadoc\fP」 |
|
5188 .TP 2 |
|
5189 o |
|
5190 クラスパスの設定 |
|
5191 .TP 2 |
|
5192 o |
|
5193 javac と javadoc がクラスを検索する方法 (tools.jar) |
|
5194 .RE |
|
5195 |
|
5196 .LP |
|
5197 .LP |
|
5198 Javadoc は、Sun Microsystems, Inc の商標です (\f2javadoc\fP コマンド自体には商標シンボルは不要)。 |