https://blog.csdn.net/huangsiqian/article/details/82725214
Javaの言語のクラスのソースファイル（.javaファイル）、パッケージコメントファイル、概要コメントファイル、およびその他の未処理のファイル：「ソース」ファイルの4種類のJavadocツールは、出力ドキュメントから生成されます。
メモパッケージファイル（パッケージコメントファイル）は、
各パッケージは、独自のドキュメンテーションコメントを持ちます。パッケージコメントファイルを作成する方法は2つあります。
package-info.java - パッケージの宣言は、パッケージコメント（注釈）、パッケージコメントとJavadocタグ（タグ）を含有してもよいです。パッケージ宣言の前にパッケージの注意事項。これは、導入された新しいJDK 5.0の特徴です。次のように。
ファイル：のJava /アプレット/ package-info.java注：コメントブロック番号の最初の行の内部文書はオプションです*
/ ** *アプレットが使用するアプレットを作成するために必要なクラスとクラスを提供し 、そのアプレットコンテキストとの通信に*。 * <P> *アプレットフレームワークは、2つのエンティティが含まれます *アプレットとアプレットコンテキストを。アプレットは、埋め込みウィンドウ（参照ある {* @link アプレットコンテキストは、いくつかのメソッドを追加したjava.awt.Panelを}クラス） *初期化、開始、およびアプレットを停止するために使用できます。 * * @since 1.0 * @see いるjava.awt 。* / パッケージ java.lang.applet。
package.html -パッケージコメントとJavadocタグのみを含めることができ、パッケージはコメントを含めることはできません。<body>要素内に含まれます。
注：ファイルの2つが含まれている場合にのみ、一つのファイルを含めることができ、その後のpackage.htmlは無視されます。次のように。
ファイル： java/applet/package.html
< HTML >は、 < BODY >は 、アプレットと、アプレットが使用するクラスの作成に必要なクラス提供し 、そのアプレットコンテキストとの通信にします。 < P > ：アプレットフレームワークは、2つのエンティティが含ま アプレットとアプレットコンテキストを。アプレットは、（参照埋め込みウィンドウである アプレットコンテキストは、いくつかの余分な方法で、{@link java.awt.Panel}クラス）を 、初期化、開始、およびアプレットを停止するために使用できます。 @since 1.0 @see java.awtの </ BODY > </ HTML >
パッケージコメントの最初の文は要約パック必要があります。Javadocツールは、特定のコンテンツのため、パッケージにコメントを書かれた要約文と、このフレーズは、Javadocのためのドキュメントコメントを書くためにどのよう:.を参照することができます
javadocツールパッケージコメントファイルには、次のように処理されます。
（のpackage.html、複製、<body>と</ body> HTMLの間にすべてをタグ付けするために）コピーされ、処理されます。
タグ現在パケット処理注釈。
テキスト挿入処理されたパケットの下部には、Java APIのドキュメントフォーマットを参照して、概要ページを生成しました。
パッケージコメントの最初の文は、パッケージの概要ページのトップにコピーされます。そして、パッケージ名と文は、概要ページのパッケージのリストに追加されます。
概要コメントファイル（概要コメントファイル）
Javadocツールは、その概要ページを生成します。概要コメントファイルは、任意の名前（一般的にはoverview.htmlという名前）と命名し、（通常はソースツリーの上）の任意の位置に配置することができます。java.appletでのパッケージソースファイルがCに含まれている場合、たとえば、：\ユーザー\のsrc \ Javaの \アプレット\ユーザー\ SRC \ overview.htmlに：ディレクトリ、あなたがCに概要コメントファイルを作成することができます 。
コンテンツの概要コメントファイルは、パッケージコメントファイルに似たHTML大きなファイルのコメントに書かれています。アプリケーションの概要またはパッケージのセットとして、コメントの最初の文には、タイトルや<身体>の間に、他のテキストと最初の文を入れないでください。埋め込まれたタグ（例えば、{@link}）に加えて、すべてのタグを中心に説明外側後に表示されなければなりません。アプリケーション@seeタグ場合、それは完全修飾名でなければなりません。
あなたがJavadocツールを実行すると、概要コメントファイル名を指定し-overviewオプションを使用します。ファイルのコメントファイルのパッケージの処理と同様のjavadocツールの処理。
コピー<body>と</ body>タグとプロセス間のすべてのもの。
処理の概要ラベル注釈が存在します。
挿入工程後のテキストの下部には、概要ページを生成しました。
概要コメントの最初の文は、概要ページの先頭にコピーされます。
他の未処理の書類（その他の未処理ファイル）
（ターゲットディレクトリJavadocをツールからコピーされた）ソース・ファイル内の任意の雑多なファイルを含むことができます。一般に、画像ファイル、Javaソース・コード・サンプル（.java）およびクラス（.class）ファイル、別のHTMLファイルを含みます。
未処理のファイルは、ソースファイルが含まれている任意のディレクトリパケット内のdocファイルで指定されたディレクトリに配置する必要があります。画像、サンプルコード、ソースファイル、.classファイル、アプレット、およびHTMLファイルを含むことができます。例えば、画像はをjava.awt.Buttonクラスのドキュメント、ホーム/ユーザー/ SRC / javaの/内のファイルbutton.gifボタンに含まれるようにする場合は / AWT / DOC-のファイル/ ディレクトリ。DOC-filesディレクトリが/ home /ユーザー/ SRC / Javaで設置すべきではありません、ご注意下さい / DOC-ファイルjavaディレクトリに直接任意のソースファイルが含まれていないため。
すべてのこれらのリンクの未処理のファイルがハードコーディングされた、なぜならJavadocツール単純にコピーしたディレクトリとそのすべての内容のターゲットにする必要があります。例えば、注釈リンクButton.javaドキュメントは見えるかもしれません
/ ** *次のようにこのボタンは、次のとおりです。 * <IMG SRC = "DOC-ファイル/ Button.gif"> * /
テストファイルおよびテンプレートファイル
一部の開発者は、彼らが対応するソースファイルの近くのソースツリーに格納されたファイルやテンプレートファイルをテストしたいと言います。言い換えれば、彼らは、ソースファイルやサブディレクトリと同じディレクトリに入れたいです。
Javadocツールは、明示的に経由で実行するために、単一のソースファイル名に渡された場合は、意図的に処理されてからそれらを防ぐために、テストおよびテンプレートファイルを無視することができます。あなたがJavadocツールを実行するために、パッケージ名またはワイルドカードを渡したい場合は、あなたは、これらのテストファイルおよびテンプレートファイルを扱っていないことを確認するために一定のルールに従う必要があります。
むしろ後者よりも、前者は正当である、あなたは、ソースファイルをコンパイルすることができ、テストファイルおよびテンプレートファイルとは異なりますが、それは最後に「の.java」することが可能です。
あなたは（サブディレクトリが無効なパッケージ名である）のサブディレクトリ内のファイルをテストすることができます。たとえば、あなたがcom.package1でソースファイルにテストファイルを追加する場合：
COM /パッケージ1 /テスト・ファイル/
Javadocツールは、任意の警告なしに、testディレクトリをスキップします。
テストファイルは、docコメントが含まれている場合、あなたは、このようなCOM /パッケージ1 /テストファイル/などのワイルドカード、着信ソースファイル名をテストすることによってテストファイルのドキュメントを生成するために、別々の実行Javadocツールを設定することができます * .javaファイル。
ソースファイルのテンプレートファイルの名前末尾に通常「の.java」、およびコンパイルすることはできません。あなたがソースディレクトリにテンプレートのソースファイルを保持したい場合は、プロセス、それを防ぐために、ダッシュ（例えばBuffer-Template.java）または名前付き他の違法なJava文字を使用することができます。
ドキュメントには、Javaソースファイルのコメント
場所アノテーションを：ドキュメントコメントは唯一のクラス、インタフェース、コンストラクタ、メソッド、またはフィールドの宣言の直前に置か。ドキュメンテーションコメントのメソッドの本体に配置されたが無視されます。
注セクションでは、マニュアル+ラベル部分を説明します。開始デリミタは/ **、ラベル部分にされた後に説明します。最初のブロックを開始するためのタグのラベルセクション、ブロックフラグは、@文字（* ** /大手、スペースと先頭のセパレータを無視する）によって定義されます。部分的にしかメジャーレーベルの説明なしにすることができます。タグセクションが開始した後、説明の主要部分から継続していません。パラメータラベルは複数行にまたがることができます。他の人がタグを複製することはできませんが、タグのいくつかの種類が繰り返すことができます：タグの数に制限はありません。例えば、タグ部@see
/ ** *この文は、このドキュメンテーションコメントのための主要な記述を開催します。 * @see java.lang.Objectの * /
ラベルやタグはブロックを埋め込まれました。
ブロックタグと（中括弧で示す）埋め込まれたタグ（@tagとして示すが（また、「独立したラベル」）と呼ぶ）{@tag}れる：タグの2種類があります。ブロックタグは無視*、スペースや区切り文字を（/ *）をリードする、行の先頭に指定する必要があります。これは、テキスト内の別の場所@文字を使用できることを意味し、ラベルの始まりとして解釈されることはありません。あなたが行の先頭として、@文字（非ラベルを開始）にしたい場合は、HTMLエンティティ＆＃064を使用し、。各ブロックはラベルの後、または次のラベル注釈付き文書の終わりまで、任意のテキストを含む関連するテキストラベルを持っています。関連するテキストは複数行にまたがることができます。どこでもテキストが埋め込まれたタグの配置を可能することができます。次の例は、ラベルに埋め込まれ、{@link} @deprecatedブロックタグを含みます。
/ ** * @deprecated {に置き換え、JDK 1.1のよう@link #setBounds（INT、INT、INT、INT）} / *
HTML形式で書かれた注意事項：テキストはHTMLで記述する必要があり、あなたはHTMLエンティティを使用する必要がありますし、HTMLタグを使用することができます。例えば、未満（<）およびより大きい（>）記号は＆LTのように記述されなければならない;及び＆GT;。同様に、アンパサンド＆アンプを書き込まなければならない;次の例は、で<B>太字のHTMLタグを示しています。
/ ** *これは、<B>ドキュメント</ b>のコメントです。 * @see java.lang.Object上位
大手*：各行の行頭のアスタリスク（*）文字はオプションです。1.4、ライン上で有力アスタリスクを省略した場合、もはや先頭のスペースを削除しません。これはあなたのコードは、<PRE>タグに直接貼り付けることができ、かつその後退に従うことができるサンプリングすることができます。ブラウザは通常、より均一にスペースを解釈します。左マージンインデント（ないセパレータ/ **または<PRE>タグ）に対して、なお。
最初の文のそれぞれは、宣言されているエンティティに関する簡潔かつ完全な説明を含む、簡単な文書注釈文である必要があります。接合部の第1の期間において、この文章は、または最初のラベルの前にブロックの端部（スペース、タブ、またはラインターミネータが続きます）。Javadocツールは、HTMLページの上部にあるメンバーの概要に最初の文をコピーします。
Javaは、あなたは、単一のステートメントで複数のフィールドを宣言することができますが、この文は一つだけドキュメンテーションコメントを持つことができます。あなたはフィールドごとに別々のドキュメンテーションコメントを追加する必要があるのであれば、あなたは別に、各フィールドを宣言する必要があります。たとえば、次のドキュメントコメントは意味がありません、それは二つのフィールド文として扱われるべきです。
/ **
*ポイントの距離（X、Y）の水平および垂直ナンバーで
* /
X、Y、int型の公共; //これを避ける
メンバー（メンバー）としてドキュメンテーションコメントを書くときには、このようなH1として<HTML見出しタグを使用しないことが最善です>や<H2>。Javadocツールは、生成されたファイルのタイトルタグ形式に影響を与える可能性がある文書の全体構造を作成するため。ただし、クラスやパッケージのコメントでタイトルタグを使用することができます。
自動複製方法の注意事項
次の2つの場合の注釈には、インタフェースクラスとメソッドを「継承」複製することができる、またはJavadocツール。注：コンストラクタ、フィールドとネストされたクラスは、ドキュメンテーションコメントを継承しません。
この方法は、ノートに記載するとメジャーまたは@リターンは、@ PARAMまたは@throwsタグ、それはでオーバーライドまたは実装方法から、（もしあれば）に対応する主説明またはタグコメントをコピーするJavadocツールの欠如。（複製アルゴリズム下記参照：継承された注釈アルゴリズムのための方法を）
具体的には、特定のパラメータの@paramタグの欠如は、このパラメータの継承階層のレプリケーション方式からコメントするとき。特定の異常@throwsタグがない場合には、例外は文がである場合にのみ、@throwsタグがコピーされています。この現象は、バージョン1.3（すべてのコメントが継承されている妨げるいかなる主説明またはタグが存在しない）以前のフォームは対照的です。
明示的に継承された - 主に中心に説明やコメントタグがメソッドにコピーされ、対応する、方法または@戻り、インラインタグ{@inheritDoc}挿入する@ paramタグまたは@throwsコメントで記載。ソースファイルは、文書が実際のコピーに注釈を付けるために使用することができるように唯一の-sourcepath、パスを指定したメソッドを継承しています。それは、クラスまたはパッケージであるかどうかは、コマンドラインに渡す必要はありません。これは以前の1.3.xとする（クラスが文書化されなければならないクラス（文書クラス））に反しています。
ノートは、次の3つのシナリオがありますクラスとインタフェースから継承します。
ときにスーパークラスのクラスメソッドのオーバーライドメソッド
ときインターフェース方法スーパーオーバーレイインターフェース方法
ときに、クラスメソッドの実装におけるインターフェース方法
は、最初の2つのケースをカバーするための方法であって、Javadocツール文書は、サブ見出し、「上書き」、それは関係なく、コメントが継承されているかどうかの、リンクをカバーする方法へのリンクが含まれて生成する方法を書き直します。
第三の場合、Javadocツールは「によって指定された」文書書き換え方法で小見出しを生成し、ポイント法では、リンクを実装します。かかわらず、注釈が継承されているかどうかの。
継承されたメソッドのアルゴリズムを注釈付き - {@inheritDoc}タグ方法ドキュメンテーションコメントなしドキュメンテーションコメントまたはメソッド場合、Javadocツールは、最も適した特定のコメントを以下のアルゴリズム検索を使用して、アルゴリズムは、プラスインターフェースではなく、スーパークラスです。
後に発生するメソッド宣言にそれら（又は延びている）ために、器具の各直接実装されたインタフェース（または拡張）を参照してください。最初のdocコメントを見つけるために、このメソッドを使用します。
ステップは、ドキュメント注釈を見つけるために失敗し、そしてこの全体のアルゴリズムのステップ1で確認したように同じ順序を配置した場合、各直接実装インターフェース（または拡張）に再帰的に適用されます。
あなたはドキュメンテーションコメントにステップ2を見つけることができない、これはクラス（ないインタフェース）である場合、オブジェクトに加えて：1、スーパークラスは、このメソッドのドキュメンテーションコメントを持つ場合、それを使用しています。2.ステップ1は、ドキュメンテーションコメントを見つけることができなかった場合は、再帰的アルゴリズムは全体のスーパークラスに適用されます。