Javadocs
Javadoc コメントは、その下にあるコード要素の記述を提供するために使用される特殊なコメントです。 /** で始まり、 */ で終わり、特定のメタデータでマークされた @ タグを含むことができます。
Javadoc は、Javadoc コメントから HTML ドキュメントを生成するための Java が提供するツールです。 JDK に付属する Javadoc ツールを使用して、プロジェクトの API リファレンスを生成できます。 IntelliJ IDEA は Javadoc ツールとの統合を提供し、IDE から直接 リファレンスガイドを作成できます。
Javadoc の正しい形式、スタイルガイド、用語と規則について詳しくは、 Javadoc ツールのドキュメントコメントの書き方(英語)を参照してください。
Javadoc コメントを書く
Javadoc コメントは手動で入力するか、IntelliJ IDEA の組み込みアクションを使用してコードに追加できます。
メソッドで Javadoc アクションを使用すると、IDE はメソッド構造に基づいて必須のタグをコメントに自動で挿入します。各パラメーターには @param 、メソッドが値を返す場合は @return 、メソッドがスローできる例外ごとに @throws が挿入されます。
自動補完を使用して Javadoc コメントを追加する。
宣言の前に
/**と入力し、 Enter を押します。 IDE はドキュメントコメントを自動で補完します。
コンテキストアクションを使用して Javadoc コメントを追加する。
エディターで宣言箇所にキャレットを置きます。
Alt+Enter を押して、 Javadoc の追加 を選択します。
Javadoc コメントのフォーマット
Javadoc コメントは HTML タグおよび Javadoc 固有のタグを使用してフォーマットできます。 本章ではよく使われるものをいくつか紹介します。
HTML タグ：
段落には
<p>を使用します。見出しには
<h1>、<h2>などを使用します。イメージを追加するには
<img>を使用します (例:<img src="jb_logo.png"/>)。空白を保持するには
<pre>を使用します。リストの場合、順序付きリストと順序なしリストの項目には
<ul>(順序なし)、<ol>(順序あり)、<li>を使用します。
インライン Javadoc タグ:
{@code text}を使用して、インラインテキストをコードとしてフォーマットします。<や> などの特殊文字を表示するには、
{@literal text}を使用します。{@link ClassName}を使用して、別のクラスまたはメソッドへのハイパーリンクを挿入します。
Javadoc タグをブロックします:
メソッドパラメーターを記述するには、
@param name descriptionを使用します。メソッドの戻り値を説明するには、
@return descriptionを使用します。@deprecated reasonを使用して、メソッドまたはクラスを非推奨としてマークします。クラスやインターフェースの作成者を指定するには、
@author nameを使用します。
エディターで Javadoc をレンダリングする。
IntelliJ IDEA を使用すると、Javadoc コメントをエディターでレンダリングできます。 レンダリングされたコメントは読みやすく、リンクをクリックして参照先のウェブページに移動できるほか、余分なタグでコードを煩雑にすることもありません。
Javadoc コメントをレンダリングするには、ガターの 
レンダリングビューの切り替え をクリックします（または Ctrl+Alt+Q を押します）。 コメントを編集するには、 
レンダリングビューの切り替え をクリックします。
デフォルトで Javadoc コメントをレンダリングする。
IDE で常にエディターで Javadoc コメントをレンダリングするように設定できます。
ガター内で
レンダリングビューの切り替え （または レンダリングビューの切り替え ）を右クリックし、 すべてのDoc コメントをレンダリング を選択します。または、 設定 （Ctrl+Alt+S ）を開き、 に移動して ドキュメントコメントをレンダリングする を選択します。
レンダリングされた Javadoc コメントを編集するには、ガターの 
レンダリングビューの切り替え をクリックします。
レンダリングされた Javadoc コメントのフォントサイズを変更する。
レンダリングされた Javadoc コメントを右クリックして 外観の調整 を選択します。
表示されたポップアップで フォントサイズ スライダーを調整します。
レンダリングされたコメントは クイックドキュメントポップアップと同じフォントサイズで表示されることに注意してください。
Javadoc リファレンスを生成
IntelliJ IDEA には、プロジェクトの Javadoc リファレンスを生成できるユーティリティがあります。
メインメニューで へ移動します。
開いたダイアログで、スコープ、つまり参照を生成するファイルまたはディレクトリのセットを選択します。
出力ディレクトリ(D) で、生成されたドキュメントを配置するフォルダーを指定します。
可視性レベル リストから、生成されたドキュメントに含まれるメンバーの可視性レベルを選択します。
Public(B): パブリッククラスとメンバーのみが含まれます。 このレベルは、
-publicJavadoc パラメーターに対応します。protected(T): パブリックおよび保護されたクラスとメンバーのみが含まれます。 このレベルは、
-protectedJavadoc パラメーターに対応します。パッケージ: プライベートなものを除くすべてのクラスとメンバーが含まれます。 このレベルは、
-packageJavadoc パラメーターに対応します。Private(I): すべてのクラスとメンバーが含まれます。 このレベルは、
-privateJavadoc パラメーターに対応します。
ロケール（たとえば
en_US.UTF-8）、コマンドライン引数、最大ヒープサイズを指定できます。 すべてのコントロールの説明については、 リファレンス を参照してください。生成 をクリックして参照を生成します。
リファレンス: Javadoc 生成ダイアログ。
JavaDoc の生成 ダイアログのコントロールは、 Javadoc ユーティリティ のオプションやタグに対応しています。
項目 | 説明 |
|---|---|
JavaDoc のスコープ | この領域を使用して、Javadoc を生成するファイル、フォルダー、パッケージのサブセットを指定します。 この スコープは、プロジェクト全体、最近変更されたファイル、現在のファイル、カスタムスコープなどにすることができます。 |
テストソースを含める(T) | 生成された Javadoc にテスト用のドキュメントコメントを含めます。 |
-sourcepath に JDK およびライブラリのソースを含める | このチェックボックスを選択すると、JDK およびライブラリソースへのパスが Javadoc ユーティリティに渡されます。 詳細については、 Javadoc ドキュメント(英語) を参照してください。 |
JDK ドキュメントへのリンク（-link オプションを使用） | このチェックボックスが選択されている場合、JDK からのクラスおよびパッケージへの参照はリンクに変わります。これは、Javadoc ユーティリティの -link(英語) オプションの使用に対応します。 このチェックボックスは、オンラインドキュメントへのリンクが SDK 設定の ドキュメントパス タブで指定されている場合にのみ有効です。 詳細については、 Javadoc(英語) のドキュメントを参照してください。 |
出力ディレクトリ(D) | 生成されたドキュメントが保存されるディレクトリへの完全修飾パスを指定します。 パスは手動で入力するか、 |
可視性レベル | 生成されたドキュメントに含めるメンバーの可視性レベルを指定します。
|
階層ツリーを生成する | クラス階層を生成します。 このチェックボックスをオフにすると、 |
ナビゲーターバーの生成 | ナビゲーターバーを生成します。 このチェックボックスをオフにすると、 |
インデックスを生成する | ドキュメントのインデックスを生成します。 このチェックボックスをオフにすると、 |
インデックスを頭文字で分ける | 文字ごとに個別のインデックスファイルを生成します。 このチェックボックスをオフにすると、 このチェックボックスは、 インデックスを生成する チェックボックスが選択されている場合にのみ使用できます。 |
@use | クラスとパッケージの使用箇所を文書化します。 選択すると、チェックボックスは |
@author |
|
@version |
|
@deprecated |
|
非推奨リスト | 非推奨リストを生成します。 チェックボックスをオフにすると、 このチェックボックスは、 @deprecated チェックボックスが選択されている場合にのみ使用できます。 |
ロケール(L) | 必要なロケールを入力します。 |
コマンドライン引数 | Javadoc に渡す追加の引数を入力します。 コマンドライン構文を使用します。 |
最大ヒープサイズ(M) | Javadoc を実行するために Java VM が使用する最大ヒープサイズを MB 単位で入力します。 |
生成したドキュメントをブラウザーで開く(G) | 生成された Javadoc をブラウザーで自動的に開きます。 |
Javadocs でカスタムタグを使用
あらかじめ定義されたタグの他にも、Javadoc コメントでカスタムタグを使えます。 後から Javadoc リファレンスを生成するときに、生成されるドキュメントにカスタムタグを 含めることができます。
カスタムタグを認識
カスタムタグを初めて使用する場合、 Javadoc 宣言の問題 インスペクションはそれをエディターで間違ったタグとしてハイライトします。 これを回避するには、認識されたタグのリストにタグを追加します。
カスタムタグの位置にキャレットを置き、 Alt+Enter を押して カスタムタグに「@tagname」を追加 を選択します。
または、 設定 （Ctrl+Alt+S ）を開いて に移動します。 リスト内で Javadoc 宣言の問題 インスペクションを見つけ、 追加のJavadoc タグ リストにタグを追加します。
Javadoc リファレンスにカスタムタグを含める
カスタムタグを HTML Javadoc 参照に含めるには、コマンドライン引数として追加します。
に移動し、 コマンドライン引数 フィールドに
-tag tagname:Xaoptcmf:"taghead"を指定します。サンプル:
-tag location:a:"Development Location:"Xaoptcmfは、ソースコード内のどこにタグを配置できるかを決定します。aを使用すると、すべての場所でタグを許可できます。 Javadoc のブロックタグについては、 Javadoc ドキュメント(英語) を参照してください。Javadoc リファレンスを生成 の説明に従って他のオプションを設定し、リファレンスガイドを生成します。
タグからの情報は、対応するページに表示されます。
Javadoc コードスタイルをカスタマイズする。
Javadoc コードスタイルは、IntelliJ IDEA がエディターで Javadoc コメントをどのようにフォーマットするかを定義します。
設定 （Ctrl+Alt+S ）を開き、 に進みます。
JavaDoc タブを見つけます。
必要に応じて コードスタイル設定 を構成します。 ダイアログ右側のセクションを使って変更をプレビューできます。
リファレンス: Javadoc コードスタイル設定。
項目 | 説明 |
|---|---|
位置合わせ | Javadoc コメントを配置する方法を定義します。
|
空白行 | Javadoc コメントに空白行を挿入する場所を定義します。
|
無効なタグ | この領域では、無効なタグを保存するかどうかを定義します。
|
その他 | この領域で、Javadoc コメントの追加のフォーマットオプションを指定します。
|
ライブラリで Javadoc を使用する。
Javadoc コメント以外にも、IntelliJ IDEA ではプロジェクトで使用しているライブラリの Javadoc もレンダリングできます。 プロジェクト設定で Javadoc が ライブラリに追加されていれば 、任意のシンボルやメソッドシグネチャーの外部 Javadoc をエディターから直接表示できます。
IntelliJ IDEA でライブラリ Javadoc を表示する。
クイックドキュメント ポップアップを呼び出します。
エディターで必要なシンボルの上にマウスを置きます。
または、シンボルにキャレットを置き、 Ctrl+Q （ ）を押します。
専用のツールウィンドウでドキュメントを開くには、もう一度 Ctrl+Q を押します。
通常 Javadoc が提供されているライブラリで IntelliJ IDEA 上では利用できない場合、Javadoc をダウンロード（組み込みのダウンロードオプション利用可）するか、手動で追加できます。
ライブラリの Javadoc をダウンロードする。
ライブラリに Javadoc を追加する最も速い方法は、Javadoc をダウンロードすることです。 ダウンロードオプションの場所は、プロジェクトで使用しているビルドツールによって異なります。
Maven ツールウィンドウを開きます。
ソース / ドキュメントのダウンロード をクリックし、 ドキュメントのダウンロード を選択します。
エディターでライブラリのシンボルまたはメソッドシグネチャーにマウスカーソルを合わせます。
表示されたポップアップで
ドキュメントのダウンロード をクリックします。
プロジェクト構造 ダイアログ（Ctrl+Alt+Shift+S ）を開き、 ライブラリ を選択します。
必要なライブラリを選択し、ダイアログ右側で Edit をクリックします。
開いたダイアログで Javadocs のダウンロード を選択し、 OK をクリックします。
変更を適用して、ダイアログを閉じます。
ライブラリに Javadoc を手動で追加する。
外部 URL を指定するか Javadoc を含む JAR ファイルを追加することで、ライブラリに Javadoc を手動で追加できます。
Javadoc の URL を指定する。
プロジェクト構造 ダイアログ（Ctrl+Alt+Shift+S ）を開き、 ライブラリ に進みます。
リストからライブラリを選択し、ダイアログの右側で
Specify Documentation URL をクリックします。表示されたダイアログでドキュメントの URL を入力し、 OK をクリックします。
変更を適用して、ダイアログを閉じます。
Javadoc 付きの JAR ファイルを追加する。
プロジェクト構造 ダイアログ（Ctrl+Alt+Shift+S ）を開き、 ライブラリ に進みます。
リストからライブラリを選択し、ダイアログの右側で
追加 をクリックします。 
開いたダイアログでドキュメントを含む JAR ファイルを選択し、 開く をクリックします。
変更を適用して、ダイアログを閉じます。
Javadoc の問題のトラブルシューティング。
Javadoc インスペクションの問題。
メソッドシグネチャーが変更された場合、IntelliJ IDEA はメソッドシグネチャーと一致しないタグをハイライトし、クイックフィックスを提案します。
コンテキストアクションを使用して修正
タグにキャレットを置き、 Alt+Enter を押して、アクションを選択します。 タグの変更や削除も可能です。
Fix doc comment action を使用して修正
タグにキャレットを置き、 Ctrl+Shift+A を押します。
fix doc commentと入力し、 Enter を押します。
Javadoc 生成エラー。
IntelliJ IDEA で Javadoc リファレンスを生成中にエラーが発生した場合、エラーの詳細は 実行 ツールウィンドウ（Alt+4 ）に表示されます。
UTF-8 エンコーディングが原因で発生したロケール名の不正を修正する。
javadoc: error – Malformed locale name: en_US.UTF-8 が発生した場合は、UTF-8 エンコーディングをコマンドライン引数に移してみてください。
メインメニューで へ移動します。
ロケール(L) フィールドをクリアします。
「コマンドライン引数 」フィールドに
-encoding utf8 -docencoding utf8 -charset utf8と入力します。-encoding：ソースファイルで使用されているエンコーディング。-docencoding：出力 HTML ファイルで使用すべきエンコーディング。-charset：Javadoc が各出力ファイルの HTML ヘッド部に挿入する文字セットです。
Javadoc リファレンスを再生成します。