Java Javadocタグの記述と見え方のサンプル

nas

JavaのJavadocタグの記述と見え方のサンプルです。
Javadocとは、Javaのソースコードから作成されるHTML形式の仕様書です。

確認環境
・Java 8
・eclipse 4.8/4.7

目次

Javadoc

  • ソースコードにJavadoc形式のコメントをすると、HTML形式のAPIドキュメントを生成できます。
  • Javadocのコメントは、「/**」(アスタリスク2つ)から「*/」までです。
  • Eclipseで、/** を入力してエンターキーを押すと残りの部分を自動入力してくれます。

Javadocタグを使用したソースサンプル

以下は、Test2というクラスとそのメソッドにJavadocタグを使用したサンプルです。

package test1;

/**
 * Test2クラスのサンプルです<br>テスト改行1<br>
 * テスト改行2
 * テスト改行3
 * @author testuser
 * @version 1.1
 */
class Test2{

  /**
   * メソッドのサンプル1です
   * 
   * @param a メソッドの引数1です
   * @param b メソッドの引数2です
   * @return intを返します
   * @throws ArithmeticException 0による除算
   * 
   */
  int calc1(int a,int b) throws ArithmeticException{
    int c;
    c = a/b;
    return c;
  }
  /**
   * メソッドのサンプル2です
   * 
   * @deprecated 処理なし
   * @return intを返します
   */
  int calc2() {
    int c = 0;
    return c;
  }
}
public class Test1 {
  public static void main(String[] args) {
    Test2 t2 = new Test2();           
    System.out.println(t2.calc1(10, 10)); //1
  }
}

4-6行目は、クラスの説明です。JavadocはHTMLタグを使用することができます。
注：<br />はエラーになります。(エラー: 自己終了要素は使用できません)
7行目の@authorは、作成者です。
8行目の@versionは、ソースコードのバージョンです。
13行目は、メソッドの説明です。
15,16行目の@paramは、メソッドの引数の説明です。このメソッドには2つ引数があるので2行で書きます。
書き方は、「@param a 日本語の説明」としたとき、引数(a)の記述が必要です。
→引数を記述しない場合Javadoc生成時にエラーが発生します。(エラー: @param nameが見つかりません)
17行目の@returnは、メソッドの戻り値の説明です。
18行目の@throwsは、メソッドが投げる例外の説明です。
書き方は、「@throws ArithmeticException 日本語の説明」としたとき、例外(ArithmeticException)の記述が必要です。
→例外を記述しない場合Javadoc生成時にエラーが発生します。(エラー: 予期しないテキストです)
29行目の@deprecatedは、非推奨項目の説明です。

 

Javadocファイルを生成したときのJavadocファイルの見え方

上記コードからJavadocファイルを生成したときのJavadocファイルの見え方です。

Javadocのクラスの概要欄

Javadocのクラスの概要欄です。赤枠の拡大版は下にあります。

 

赤枠の拡大版
①クラスの説明が表示されています。
HTMLのBRタグを入れた箇所が改行されています。

 

Javadocのクラスの説明欄

Javadocのクラスの説明欄です。赤枠の拡大版は下にあります。

 

赤枠の拡大版
①クラスの説明が表示されています。HTMLのBRタグを入れた箇所が改行されています。
②バージョンが表示されています。
③作成者が表示されています。

 

Javadocのメソッドの概要の説明欄

Javadocのメソッドの概要の説明欄です。
①calc1メソッドの説明が表示されています。
②calc2メソッドの説明が表示されています。@deprecatedが「推奨されていません。」という文言になっています。

 

Javadocのメソッドの詳細の説明欄

Javadocのメソッドの詳細の説明欄です。赤枠の拡大版は下にあります。

 

赤枠の拡大版
①calc1メソッドの説明が表示されています。
②パラメータは、2つ引数があるので2行表示されます。
③戻り値の説明が表示されています。
④例外の説明が表示されています。
⑤calc2メソッドの説明が表示されています。
⑥@deprecatedは「推奨されていません。」という文言になっています。

 

Javadocタグ

上記サンプルコードにあるJavadocタグです。

Javadocタグ 説明
@author 作成者を記述します
@version バージョンを記述します
@param 引数の説明を記述します
@return 戻り値の説明を記述します
@throws 例外の説明を記述します
@deprecated 非推奨項目であることを表します

以下は、オラクルのjavadocのページのリンクです。その他のJavadocタグもあります。
https://docs.oracle.com/javase/jp/8/docs/technotes/tools/windows/javadoc.html

関連の記事

Eclipse Javadocの生成方法

△上に戻る