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 パラグラフの情報を出力する。

$ javadoc -author Example.java

-d directory

ファイルをdirecotryで指定したディレクトリに出力します。

-docencoding name

出力エンコーディング名を指定する。

-encoding name

ソースファイルのエンコーディング名を指定する。

-nodeprecated

@deprecated 情報を除外します。

-public

public クラスとメンバのみを示します。

-protected

protected/public クラスとメンバを示します(デフォルト)。

-sourcepath pathlist

ソースファイルのある場所を指定します。

-version

@versionパラグラフの情報を出力します。

パラグラフ

コメントはクラスかメソッドの直前に記述します。コメント中にアットマーク記号に続けてjavadoc パラグラフを記述します。パラグラフはクラスとメソッド両方に記述できるものと、クラスのみに記述できるもの、メソッドのみに記述するものがあります。次にパラグラフの一覧を示します。

@author

クラスの著者名を記述する。javadoc コマンドに -author オプションを指定して実行すると、著者名が出力されるようになる。

/**
  @author 井上和
*/
public class ExampleClass {

}

メソッドに対しては指定できない。

@deprecated

実装しているものの、使用を推奨しないクラス又はメソッドについて説明する。

/**
  @deprecated V2.0から非推奨
*/
public class ExampleClass {

}

メソッドに対しても指定できる。

public class ExampleClass {
  /**
    @deprecated V2.0から非推奨
  */
  public void exampleMethod() {

  }
}

@exception

メソッドがスローする例外と説明を記述する。@throws パラグラフと同じ。

public class ExampleClass {
  /**
    @exception java.lang.AssertionError アサーションに失敗した
    @exception java.lang.NullPointerException nullオブジェクトにアクセスした
  */
  public void exampleMethod() {

  }
}

クラスに指定することはできない。

link

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

リンクを挿入します。

param

@param 引数名 引数の説明

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

@return

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

public class ExampleClass {
  /**
    @return 成功したときはtrue、失敗したときはfalseを返す
  */
  public boolean isExample() {

  }
}

see

@see 関連項目

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

@since

クラス又はメソッドが導入されたバージョンを記述する。

/**
  @version 1.1
  @since 1.0
*/
public class ExampleClass {
  /**
    @since 1.0
  */
  public ExampleClass() {

  }
  /**
    @since 1.1
  */
  public ExampleClass(int n) {

  }
}

@throws

メソッドがスローする例外と説明を記述する。@exception パラグラフと同じ。

public class ExampleClass {
  /**
    @exception java.lang.AssertionError アサーションに失敗した
    @exception java.lang.NullPointerException nullオブジェクトにアクセスした
  */
  public void exampleMethod() {

  }
}

クラスに指定することはできない。

@version

クラスのバージョンを記述する。javadoc コマンドに -version オプションを指定して実行すると、バージョンが出力されるようになる。

/**
  @version 1.0
*/
public class Example {

}

メソッドに対しては指定できない。

次に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