Javadoc

概要

Javadocとは、Java言語のソースコードに一定の書式でコメントを記述することで、クラスの説明やメソッドの呼び出し方などの仕様をHTMLなどの文書形式でまとめてくれる仕組み。また、そのためのコメントの書式。

各開発者がJavadocの記法に従ってソースコード内にコメントを記すことで、人によらず一定の形式でクラスやAPIの説明を生成することができる。コードとは別に仕様などを説明する文書（ドキュメント）を作成・管理しなくてよいため、ドキュメントの更新漏れなどが減り、最新の状態を正確に把握しやすくなる。

Javaのソースコード中でコメントは /∗ と ∗/ で括られた領域に書かれるが、先頭が /∗∗ になっているコメントがJavadocによって仕様書に収録される。各項目が何を意味するかは「タグ」と呼ばれる短い文字列で示される。

例えば、「@author」は開発者名、「@version」は対象のバージョン番号、「@param」はメソッドの引数、「@return」はメソッドの戻り値、「@throws」あるいは「@exception」はメソッドが投げる例外、「@deprecated」は廃止されたクラスやメソッド、「@see」は関連するクラスやメソッドといった具合である。

コメント内にはHTMLタグや画像ファイルへの参照などを記述することもできる。また、各ソースファイルに記述されるコメントの他に、APIやパッケージなどの全体についての説明などを外部の別のファイル（package-info.java）として管理することができる。

専用のツールを用いることで、Javadocの内容を反映したHTMLファイルが自動生成される。標準ではJDKなどに含まれるコマンドラインツールを利用するが、Javaに対応したIDE（統合開発環境）やビルドツールなどの多くはJavadoc対応となっており、逐一明示的に操作しなくても自動的にファイルの生成や更新を行ってくれる。

(2023.12.14更新)