Javadoc

Javadoc コメントは、その下にあるコード要素の説明を提供するための特別なコメントです。コメントは /** で始まり、*/ で終わります。また、特定のメタデータを持つ @ でマークされたタグを含むことができます。

Javadoc は、Javadoc コメントから HTML ドキュメントを生成するための Java が提供するツールです。JDK に付属する Javadoc ツールを使用して、プロジェクトの API リファレンスを生成できます。IntelliJ IDEA は Javadoc ツールとの統合を提供し、IDE から直接リファレンスガイドを作成できます。

Javadoc の正しい形式、スタイルガイド、用語と規則について詳しくは、Javadoc ツールのドキュメントコメントの書き方(英語)を参照してください。

Javadoc をレンダリングする

IntelliJ IDEA を使用すると、Javadoc コメントをエディターでレンダリングできます。レンダリングされたコメントは読みやすく、余分なタグでコードがオーバーロードされることもありません。

必要なドキュメントコメントの横のガターでをクリックして（または Ctrl+Alt+Q を押して）、レンダリングビューを切り替えます。をクリックしてコメントを編集します。

レンダリングされた Javadoc コメントを使用すると、リンクをクリックして参照先の Web ページに移動したり、参照先のトピックの簡単なドキュメントを表示したりできます。

フォントサイズを変更するには、エディターで Javadoc コメントを右クリックし、コンテキストメニューから「フォントサイズの調整」を選択します。レンダリングされたコメントは、クイックドキュメントポップアップと同じフォントサイズで表示されることに注意してください。

デフォルトで Javadoc をレンダリングする

エディターで常に Javadoc をレンダリングするように IDE を構成できます。

(ガターのアイコンまたは ) を右クリックし、すべてレンダリングオプションを有効にします。
または、設定ダイアログ Ctrl+Alt+S でエディター | 一般 | 外観を選択し、ドキュメントコメントをレンダリングするオプションを有効にします。

レンダリングされた Javadoc を編集するには、コメントの横のガターにあるアイコンをクリックします。

Javadoc コメントを書く

Javadoc コメントの追加

自動コメントを使用して Javadoc を追加する

ドキュメントコメントについては、IntelliJ IDEA ではデフォルトで補完が有効になっています。

宣言の前に /** と入力し、Enter を押します。IDE は、ドキュメントコメントを自動的に補完します。

Javadoc コメントの自動挿入を無効にできます。設定ダイアログ Ctrl+Alt+S で、エディター | 一般 | スマートキーに移動し、ドキュメントコメントスタブを挿入するチェックボックスをオフにします。

コンテキストアクションを使用して Javadoc コメントを追加する

エディターの宣言にキャレットを置き、Alt+Enter を押して、リストから Javadoc の追加を選択します。

Kotlin では、推奨スタイル(英語)でパラメーターと戻り値の説明をドキュメントコメントに直接組み込む必要があるため、@param タグやその他のタグは生成されません。

Javadoc コメントのフォーマット

Javadoc は HTML タグと特殊タグによるフォーマットをサポートしています。詳しくは Javadoc ツールのドキュメントコメントの書き方 (英語) (oracle.com) を参照してください。

以下に 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 を使用します。
@deprecated reason を使用して、メソッドまたはクラスを非推奨としてマークします。
クラスの作成者を指定するには、@author name を使用します。

利用可能なタグの完全なリストは、Javadoc ツールのドキュメントコメントの書き方 (英語) (oracle.com) から取得してください。

Javadoc の修正

メソッドシグネチャーが変更された場合、IntelliJ IDEA はメソッドシグネチャーと一致しないタグをハイライトし、クイックフィックスを提案します。

コンテキストアクションを使用して修正する

タグにキャレットを置き、Alt+Enter を押して、アクションを選択します。タグの変更や削除も可能です。

「ドキュメントコメントを修正」アクションを使用して修正する

ドキュメントコメントアクションを修正を使用して、宣言の変更を考慮して既存の Javadoc コメントを更新することもできます。

クラス、メソッド、関数、フィールドにキャレットを置き、Ctrl+Shift+A を押します。
fix doc comment と入力し、Enter を押します。

Javadoc でカスタムタグを使用する

Javadocs コメントでは、定義済みのタグに加えてカスタムタグを使用できます。後で、 API リファレンスガイドに含めることができます。

カスタムタグを認識する

カスタムタグを初めて使用する場合、Javadoc 宣言の問題インスペクションはそれをエディターで間違ったタグとしてハイライトします。これを回避するには、認識されたタグのリストにタグを追加します。

カスタムタグにキャレットを置き、Alt+Enter を押して、カスタムタグに「@tagname」を追加を選択します。
または、Ctrl+Alt+S を押して IDE 設定を開き、エディター | インスペクションを選択します。リスト内で Javadoc 宣言の問題インスペクションを見つけて、タグを追加の JavaDoc タグリストに追加します。

Javadoc リファレンスにカスタムタグを含める

カスタムタグを HTML Javadoc 参照に含めるには、コマンドライン引数として追加します。

ツール | JavaDoc を生成に移動し、コマンドライン引数フィールドに -tag tagname:Xaoptcmf:"taghead" を指定します。
サンプル: -tag location:a:"Development Location:"
Xaoptcmf は、ソースコード内のどこにタグを配置できるかを決定します。a を使用すると、すべての場所でタグを許可できます。Javadoc のブロックタグの詳細については、Oracle のドキュメント(英語)を参照してください。
Javadoc リファレンスを生成するの説明に従って他のオプションを設定し、リファレンスガイドを生成します。
タグからの情報は、対応するページに表示されます。

Javadoc リファレンスを生成する

IntelliJ IDEA には、プロジェクトの Javadoc リファレンスを生成するためのユーティリティが用意されています。

メインメニューで、ツール | JavaDoc を生成に移動します。
開いたダイアログで、スコープ、つまり参照を生成するファイルまたはディレクトリのセットを選択します。
出力ディレクトリで、生成されたドキュメントを配置するフォルダーを指定します。
出力ディレクトリは必須フィールドです。空である限り Javadoc ファイルを生成できません。
可視性レベルリストから、生成されたドキュメントに含まれるメンバーの可視性レベルを選択します。
- Private: すべてのクラスとメンバーが含まれます。このレベルは、-private Javadoc パラメーターに対応します。
- パッケージ : プライベートなものを除くすべてのクラスとメンバーが含まれます。このレベルは、-package Javadoc パラメーターに対応します。
- Protected: パブリックおよび保護されたクラスとメンバーのみが含まれます。このレベルは、-protected Javadoc パラメーターに対応します。
- Public: パブリッククラスとメンバーのみが含まれます。このレベルは、-public Javadoc パラメーターに対応します。
ロケール（たとえば en_US.UTF-8）、コマンドライン引数、最大ヒープサイズを指定できます。
生成をクリックして参照を生成します。

Javadoc の生成スコープの指定ダイアログ

ツール | JavaDoc を生成ダイアログは、Javadoc(英語) ユーティリティを呼び出します。ダイアログのコントロールは、このユーティリティのオプションとタグに対応しています。

項目	説明
JavaDoc のスコープ	この領域を使用して、Javadoc を生成するファイル、フォルダー、パッケージのサブセットを指定します。このスコープは、プロジェクト全体、最近変更されたファイル、現在のファイル、カスタムスコープなどにすることができます。
テストソースを含める	生成された Javadoc にテスト用のドキュメントコメントを含めます。
-sourcepath に JDK およびライブラリのソースを含める	このチェックボックスを選択すると、JDK およびライブラリソースへのパスが Javadoc ユーティリティに渡されます。詳細については、ドキュメント(英語)を参照してください。
JDK ドキュメントへのリンク（-link オプションを使用）	このチェックボックスが選択されている場合、JDK からのクラスおよびパッケージへの参照はリンクに変わります。これは、Javadoc ユーティリティの -link(英語) オプションの使用に対応します。このチェックボックスは、オンラインドキュメントへのリンクが SDK 設定のドキュメントパスタブで指定されている場合にのみ有効です。詳細については、Javadoc(英語) のドキュメントを参照してください。
出力ディレクトリ	生成されたドキュメントが保存されるディレクトリへの完全修飾パスを指定します。パスを手動で入力するか、をクリックしてダイアログで場所を選択します。指定された値は、Javadoc ユーティリティの `-d` パラメーターに渡されます。指定したディレクトリがシステムに存在しない場合は、ディレクトリを作成するように求められます。出力ディレクトリを指定しない限り、OK ボタンは無効になります。
可視性レベル	生成されたドキュメントに含めるメンバーの可視性レベルを指定します。 Private: すべてのクラスとメンバーが含まれます。このレベルは、`-private` Javadoc パラメーターに対応します。パッケージ : プライベートなものを除くすべてのクラスとメンバーが含まれます。このレベルは、`-package` Javadoc パラメーターに対応します。 Protected: パブリックおよび保護されたクラスとメンバーのみが含まれます。このレベルは、`-protected` Javadoc パラメーターに対応します。 Public: パブリッククラスとメンバーのみが含まれます。このレベルは、`-public` Javadoc パラメーターに対応します。
階層ツリーを生成する	クラス階層を生成します。このチェックボックスをオフにすると、`-notree` パラメーターが Javadoc に渡されます。
ナビゲーターバーの生成	ナビゲーターバーを生成します。このチェックボックスをオフにすると、`-nonavbar` パラメーターが Javadoc に渡されます。
インデックスを生成する	ドキュメントのインデックスを生成します。このチェックボックスをオフにすると、`-noindex` パラメーターが Javadoc に渡されます。
インデックスを頭文字で分ける	文字ごとに個別のインデックスファイルを生成します。このチェックボックスをオフにすると、`-splitindex` パラメーターが Javadoc に渡されます。このチェックボックスは、インデックスを生成するチェックボックスが選択されている場合にのみ使用できます。
@use	クラスとパッケージの使用箇所を文書化します。選択すると、チェックボックスは `-use` Javadoc パラメーターに対応します。
@author	`@author` の段落を含めます。選択すると、チェックボックスは `-author` Javadoc パラメーターに対応します。
@version	`@version` の段落を含めます。選択すると、チェックボックスは `-version` Javadoc パラメーターに対応します。
@deprecated	`@deprecated` 情報を含めます。チェックボックスをオフにすると、`-nodeprecated` パラメーターが Javadoc に渡されます。
非推奨リスト	非推奨リストを生成します。チェックボックスをオフにすると、`-nodeprecatedlist` パラメーターが Javadoc に渡されます。このチェックボックスは、@deprecated チェックボックスが選択されている場合にのみ使用できます。
ロケール	必要なロケールを入力します。
コマンドライン引数	Javadoc に渡す追加の引数を入力します。コマンドライン構文を使用します。
最大ヒープサイズ	Javadoc を実行するために Java VM が使用する最大ヒープサイズを MB 単位で入力します。
生成したドキュメントをブラウザーで開く	生成された Javadoc をブラウザーで自動的に開きます。

トラブルシューティング

javadoc: error – Malformed locale name: en_US.UTF-8

ロケールフィールドをクリアします。その他のコマンドライン引数フィールドに -encoding utf8 -docencoding utf8 -charset utf8 を追加します。

-encoding は、ソースファイルのエンコーディングを指定します。-docencoding は出力 HTML ファイルのエンコーディングを指定し、-charset は出力ファイルの HTML ヘッドセクションで指定された文字セットです。

リファレンス: Javadoc コードスタイル

Javadoc のコードスタイルを設定できます。Ctrl+Alt+S を押して設定を開き、エディター | コードスタイル | Java | Javadoc を選択します。必要に応じてオプションを設定し、ダイアログの右側の部分を使用して変更をプレビューします。

コードの整形からコードを再フォーマットする方法を学びます。

項目	説明
位置合わせ	Javadoc コメントを配置する方法を定義します。パラメーター説明の位置を合わせる : パラメーターの説明を最長のパラメーター名に合わせて配置します。それ以外の場合は、説明は対応するパラメーター名から 1 つのスペースで区切られます。例外の説明の位置を合わせる : スローされた例外の説明を最長の例外名に合わせて配置します。それ以外の場合は、説明と例外名は 1 つのスペースで区切られます。
空白行	Javadoc コメントに空白行を挿入する場所を定義します。説明の後 : Javadoc コメントの説明セクションの後に空白行を自動的に挿入します。パラメーター説明の後 : `@param` タグのグループの後に空行を自動的に挿入します。 return タグの後 : `@return` タグの後に空行を自動的に挿入します。
無効なタグ	この領域では、無効なタグを保存するかどうかを定義します。無効なタグを維持する : `@invalidTag` を保存します。空の @param タグを維持する : 説明なしで `@param` タグを保持します。空の @return タグを維持する : 説明なしで `@return` タグを保持します。空の @throws タグを維持する : 説明なしで `@throws` タグを保持します。
その他	この領域で、Javadoc コメントの追加のフォーマットオプションを指定します。行頭のアスタリスク (*) を許可する : Javadoc コメントの各行をアスタリスクで始めます。 @exception の代わりに @throws を使用する : `@throws` タグを使用します。右マージンで折り返す : 右マージンを超えるテキストを次の行に折り返します。空白行に "<p>" を生成する : 空の行に `</p>` タグを自動的に挿入します。空白行を維持する : 空の行を手動で追加するには、このチェックボックスを選択します。 1 行のコメントは折り返さない : 開始タグと終了タグを使用して、1 行に短いコメントを付けます。改行を保持する : このチェックボックスが選択されていない場合（デフォルト）、ラインフィードは再フォーマット時に保持されません。これは、コメントを段落の境界内でフォーマットして、最小限のスペースを占める必要がある場合に便利です。このチェックボックスをオンにすると、改行は保存されます。パラメーターの説明の前に改行する : Javadoc パラメーターの説明（ある場合）を新しい行に配置します。継続インデント値に基づいてインデントを使用します。継続行をインデントする : 複数行コメントの後続の行をインデントします。