javadocはJavaのソースファイルからHTML形式のリファレンスを作成するコマンドです。Javaのクラスやメソッドの説明する文書をソースファイルのコメントから自動的に生成してくれるため、たいへん便利な機能です。
Javaではインプリメンテーションコメントとドキュメンテーションコメントの2種類のコメントを書くことができます。インプリメンテーションコメントは
/* ... */
と
//
によるものです。ドキュメンテーションコメントは
/** ... */
という形式です。ドキュメンテーションコメントはjavadocツールを使用してHTMLファイルとしてコメントを抜粋することができます。
/**
* XQueryによる検索
* @param query XQuery文字列
* @return 成功したときはtrue、失敗したときはfalseを返す
*/
static boolean executeXQuery(String query) {
コマンドラインからjavadocコマンドを実行すると、JavaのソースファイルからHTMLファイルを生成します。
javadoc [option ...] [package ] source-file ...
$ javadoc XQuery.java
次にjavadocのコマンドオプションを示します。
@authorパラグラフの情報を出力します。
ファイルをdirecotryで指定したディレクトリに出力します。
出力エンコーディング名を指定する。
ソースファイルのエンコーディング名を指定する。
@deprecated 情報を除外します。
public クラスとメンバのみを示します。
protected/public クラスとメンバを示します(デフォルト)。
ソースファイルのある場所を指定します。
@versionパラグラフの情報を出力します。
コメントはクラスかメソッドの直前に記述します。コメント中にアットマーク記号に続けてjavadoc パラグラフを記述します。パラグラフはクラスとメソッド両方に記述できるものと、クラスのみに記述できるもの、メソッドのみに記述するものがあります。次にパラグラフの一覧を示します。
パラグラフ | クラス | メソッド |
---|---|---|
author | OK | NG |
deprecated | OK | OK |
exception | NG | OK |
link | OK | OK |
param | NG | OK |
return | NG | OK |
see | OK | OK |
since | OK | OK |
throws | NG | OK |
version | OK | NG |
inheritDoc | NG | OK |
@author 著者名
著者名を記述します。javadocに-authorオプションを指定して実行すると、著者名が出力されるようになります。
@deprecated コメント
実装しているものの、使用を推奨しないものについて説明します。
@exception 例外クラス名 説明
スローされる可能性がある例外クラス名と説明を記述します。throws と同じです。
{@link クラス名#メンバ名 表示テキスト}
リンクを挿入します。
@param 引数名 引数の説明
メソッドのパラメータ(引数)の名前と説明を記述します。
@return 戻り値
メソッドの戻り値の説明を記述します。
@see 関連項目
関連項目について記述します。関連項目にはクラス名やメソッド名、変数名、URLを記述することもできます。
@since バージョン
導入されたバージョンを記述します。
@throws 例外クラス名 説明
スローされる可能性がある例外クラス名と説明を記述します。exception と同じです。
@version バージョン
バージョンを記述します。javadocに-versionオプションを指定して実行すると、バージョンが出力されるようになります。
次にjavadoc用にコメントを入れたJavaソースプログラムの例を示します。
/**
* サンプルクラス
* @author Rika Ishikawa
* @version 1.2
*/
public class SampleClass extends Object {
private static String field1;
/**
* サンプルメソッド
* @param query XQuery文字列
* @return 成功したときはtrue、失敗したときはfalseを返す
* @see java.lang.String
* @see java.lang.String#equals(Object)
* @see <a href="./newmethod.html">newMethod</a>
* @see #newMethod(int)
* {@link #newMethod(int) newMethod}メソッドを使ってください。
*/
static boolean oldMethod(String query) {
...
}
/**
* サンプルメソッド
* @param num 個数
* @since 1.1
* @see #field1
*/
static boolean newMethod(int num) {
スーパークラス(継承元のクラス)のメソッドと同じJavadocコメントが生成される。スーパークラスのメソッドをオーバーライドしたメソッドに対して指定できる。
たとえば、スーパークラスで以下のようなJavadocコメントが記述されているとする。
public class SuperClass {
/**
* Sample method
*
* @param param Sample parameter
* @return Sample return
*/
int overrideMethod(int param) {
return 1;
}
}
上記クラスを継承してメソッドをオーバーライドする場合は、スーパークラスと同じJavadocコメント記述せずに@inheritDocを指定すればよい。
public class SubClass extends SuperClass {
/**
* {@inheritDoc}
*/
int overrideMethod(int param) {
return 2;
}
}
javadocを実行した際、「Foo.java:1: エラー: この文字は、エンコーディングMS932にマップできません」とエラー出力された場合、エンコーディングを指定してjavadocを実行する。
$ javadoc -encoding UTF-8 -docencoding Shift-JIS Example.java