Java Javadocと見え方のサンプル

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

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

目次

サンプル Javadocと見え方
  Javadocを生成する方法
  Javadocタグ
  エラー: この文字は、エンコーディングMS932にマップできません

Javadocと見え方

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

Javadocのサンプルです。

package test1;

/**
 * Test1クラスのサンプルです<br>テスト改行1<br>
 * テスト改行2
 * テスト改行3
 * @author testuser
 * @version 1.1
 */
public class Test1{
  /**
   * メソッドのサンプル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;
  }
}

クラスの説明

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

4行目は、HTMLタグの<br>を使用しています。改行されます。
注:スラッシュ付きの<br />はエラーになります。(エラー: 自己終了要素は使用できません)
7行目の@authorは、作成者です。
8行目の@versionは、ソースコードのバージョンです。

クラスのサマリーは以下のように表示されます。

クラスの説明は、以下のように表示されます。

 

メソッドの説明

   * メソッドのサンプル1です
   * 
   * @param a メソッドの引数1です
   * @param b メソッドの引数2です
   * @return intを返します
   * @throws ArithmeticException 0による除算

12行目からは、メソッドの説明です。
14,15行目の@paramは、メソッドの引数の説明です。このメソッドには2つ引数があるので2行で書きます。
書き方は、「@param a 日本語の説明」としたとき、引数(a)の記述が必要です。
引数を記述しない場合Javadoc生成時にエラーが発生します。(エラー: @param nameが見つかりません)
16行目の@returnは、メソッドの戻り値の説明です。
17行目の@throwsは、メソッドが投げる例外の説明です。
書き方は、「@throws ArithmeticException 日本語の説明」としたとき、例外(ArithmeticException)の記述が必要です。
例外を記述しない場合Javadoc生成時にエラーが発生します。(エラー: 予期しないテキストです)

メソッドのサマリーは以下のように表示されます。

メソッドの説明は、以下のように表示されます。

 

メソッドを非推奨にした場合

   * @deprecated 処理なし
   * @return intを返します

28行目の@deprecatedは、非推奨項目の説明です。

メソッドのサマリーは以下のように表示されます。

メソッドの説明は、以下のように表示されます。

Javadocを生成する方法

プロジェクトやコードを右クリックし「エクスポート」からJavaDocを選択して出力します。

Javadocタグ

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

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

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

エラー: この文字は、エンコーディングMS932にマップできません

EclipseのJavaDoc出力時に以下のエラーが発生する場合は
(エラー: この文字は、エンコーディングMS932にマップできません)
「Javadocの生成」ダイアログの「追加のJavadocオプション」に以下を記述します。
-encoding UTF-8
-charset UTF-8

excel20_2

関連の記事

Eclipse Javadocの生成方法

△上に戻る