Javadocとは、サン・マイクロシステムズが開発したコンピュータソフトウェアのひとつで、JavaのソースコードからHTML形式のAPI仕様書を生成するプログラミングツールである[1]。広義ではJavadocに対応した形式のコメントを指す。
Java Development Kit (JDK) やOpenJDKのようなJavaのソフトウェア開発キットに含まれるCUI/CLIベースのコマンドラインツールであるが、Javaに対応した多くの統合開発環境 (IDE) ではJavadocをGUIから直感的に操作することもできる。
JavadocはJavaクラスの仕様書の標準の書式であり、IDEの中にはJavadocコメントの記述支援機能やドキュメントのプレビュー表示機能などを備えているものもある[2]。
なお、HTML形式は標準の書式であり、カスタマイズにより変更可能である。
サンはのちにオラクルに買収されたが、Javadocに関するドキュメントもオラクルに移管されている。
開発者はソースコードにコメントを記述するときに、ある程度の決まった形式の文章とJavadocタグを使用する。ソースのコメントのうち、/**で始まるものが、生成されたHTMLに含まれることになる。Javadocタグは、頭に@（単価記号）が付く。いくつかのタグはテーブル（表）用のものである。
/**
@
@Deprecated
{@link package.class#member label}
Serializable
ObjectStreamField
writeObject
Externalizable.writeExternal(ObjectOutput)
ObjectOutput.writeObject(Object)
ObjectInput.readObject()
writeExternal(ObjectOutput)
readExternal(ObjectInput)
Javadocコメントの記述例。サンプルには英語が含まれているが、適切なテキストエンコーディング（通例UTF-8）を使用することで日本語の使用も可能である。
/** * クラスの説明. * <pre> * ピリオド(.)または句点(。)で終わるところまでが、 * クラス一覧の概要に説明されるところであり、 * ピリオド以降は説明の概要には含まれず、クラスの説明に含まれる。 * このように、JavadocにはHTMLタグを使用することができる。 * </pre> * @param <T1> 総称型パラメータの説明 * @param <T2> 総称型パラメータの説明 * @author Wikipedian * @author Second author * @version 1.6 * @since 1.0 */ public class JavadocSample<T1, T2 extends List> { /** * @serial 直列化可能データの説明 */ private int x; /** * Validates a chess move. * @author John Doe * @param theFromFile File of piece being moved * @param theFromRank Rank of piece being moved * @param theToFile File of destination square * @param theToRank Rank of destination square * @return true if a valid chess move or false if invalid */ boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) { //... } /** * 非推奨メソッド。 * @deprecated このメソッドは非推奨です。 * @throws SomeException 例外の説明 */ String deprecatedMethod() { //... } /** * メソッドの説明。 * @param t 説明 * @throws SomeException 例外の説明 * @throws Exception 例外の説明 * @return String型の値 * @since 1.5 * @see "関連" * @see <a href="http://www.example.com/">Example</a> * @see String#equals(Object) equals */ String add(T1 t) throws SomeException, Exception { //... } }
ドキュメント生成には、これらのJavadocコメントのほかに、パッケージやAPI全体の概要を説明するコメントファイルや画像ファイルを参照することができる。
ドキュメント全体の概要を示す概要コメントファイル (overview.html) を記述する。これらの文法は以下のような簡単なHTMLとなる。
<html> <body> ここに概要コメントを記述する。 </body> </html>
概要コメントファイル (overview.html) はJavadocコマンド実行時に-overviewオプションでディレクトリパスを指定するか、または、パッケージを置いているソースツリーのルートにoverview.htmlファイルを置くことでドキュメントに含められる。
package-info.javaというファイルにコメントを記述する。JDK 1.4 までは package.html に記載した。これは以下のように、クラスやメソッドなどに記述するJavadocコメントと同じ要領で済む。ただし、packageキーワードを用いてパッケージ宣言しなければならない。
/** * ここにパッケージの概要を記述する。 * @since 1.5 */ package com.example.wikipedia;
この記法は、Java SE 5から登場したアノテーションには、パッケージにも指定できるものがあるために用意された。これにより、package-info.javaにはアノテーションも保存でき、たとえばパッケージに対して@Deprecatedアノテーションを指定できるようになった。package.htmlではアノテーションが使用できないため、package-info.javaの使用はpackage.htmlよりも推奨されている。
Javadocで生成するドキュメンテーションには画像やJavaソースコードなどを含めることもできる。画像を置くには、画像を表示したいクラスがあるディレクトリにdoc-filesという名前のディレクトリを作成し、そこに画像をコピーする。そしてこの画像のリンクを実際に張るには以下のようにJavadocコメントに明示的に記述する必要がある。
/** * 画像ファイル * <img src="doc-files/image.gif" /> */
Javadocの生成は、そのままでは複雑なコマンドラインを必要とする。とくに設定を細かくすると、バッチファイルやシェルスクリプトとして記述するだけでも膨大なものになる。そこでNetBeansやEclipseなどのIDEやApache AntのようなビルドツールやApache Mavenのようなプロジェクト管理ツールを使うことが薦められている。
JavadocにはJavadocのタグを自作できる機能Docletがある。これを用いて、Apache Tomcatの設定ファイルweb.xmlの内容をJava ServletソースコードのJavadocコメント上に記述してXDocletを用いてweb.xmlを自動生成するといったことが可能になる。このほかにも、Javadocコメントから他のJavaソースコードやデータベーススキーマやUMLのクラス図を自動生成するといったことが可能になり、開発効率が飛躍的に向上する。
これはEnterprise JavaBeansやApache Struts、UML、Hibernate、JBossなどにも使われている。ただし現在では、これらの多くがJavadocによる自動生成の代わりに、Java SE 5から登場したアノテーションで代替することが可能になった。