javadoc

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のコマンドオプション

次にjavadocのコマンドオプションを示します。

-author: @authorパラグラフの情報を出力します。
-d directory: ファイルをdirecotryで指定したディレクトリに出力します。
-docencoding name: 出力エンコーディング名を指定する。
-encoding name: ソースファイルのエンコーディング名を指定する。
-nodeprecated: @deprecated 情報を除外します。
-public: public クラスとメンバのみを示します。
-protected: protected/public クラスとメンバを示します(デフォルト)。
-sourcepath pathlist: ソースファイルのある場所を指定します。
-version: @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

@author 著者名

著者名を記述します。javadocに-authorオプションを指定して実行すると、著者名が出力されるようになります。

deprecated

@deprecated コメント

実装しているものの、使用を推奨しないものについて説明します。

exception

@exception 例外クラス名 説明

スローされる可能性がある例外クラス名と説明を記述します。throws と同じです。

link

{@link クラス名#メンバ名 表示テキスト}

リンクを挿入します。

param

@param 引数名 引数の説明

メソッドのパラメータ（引数）の名前と説明を記述します。

return

@return 戻り値

メソッドの戻り値の説明を記述します。

see

@see 関連項目

関連項目について記述します。関連項目にはクラス名やメソッド名、変数名、URLを記述することもできます。

since

@since バージョン

導入されたバージョンを記述します。

throws

@throws 例外クラス名 説明

スローされる可能性がある例外クラス名と説明を記述します。exception と同じです。

version

@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) {

inheritDoc

スーパークラス（継承元のクラス）のメソッドと同じ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の使用例

javadocを実行した際、「Foo.java:1: エラー: この文字は、エンコーディングMS932にマップできません」とエラー出力された場合、エンコーディングを指定してjavadocを実行する。

$ javadoc -encoding UTF-8 -docencoding Shift-JIS Example.java