Javadoc 書き方のサンプル

JavaのJavadocの書き方のサンプルです。(確認環境:Java, Eclipse, STS)

目次

サンプル Javadocとは
  Javadocを作成する
  クラス上のコメント / メソッド上のコメント / フィールド上のコメント
  メソッドを非推奨にした場合 @deprecated
  エラー: この文字は、エンコーディングMS932にマップできません

Javadocとは

  • Javadocとは、Javaのソースコードから生成されるHTML形式のコードの仕様書です。
    改行の<br>等も使用できます。
  • Eclipseで、/** を入力してエンターキーを押すとJavadoc形式で自動入力されコメントになります。コメントの修正も可能です。
  • コメントをこの形式にしておくと、Javadocにコメントが反映されます。

Javadocのコメントの作り方

/** を入力してエンターキーを押す

 

Javadocを作成する

1.Javadocの形式でコメントをクラスの上、フィールドの上、メソッドの上に書いています。
Javadocでそれぞれクラス、フィールド、メソッドの説明になります。

package test1;

/**
 * Test1クラスのサンプルです<br>
 * テスト改行1<br>
 * テスト改行2 テスト改行3
 * 
 * @author testuser
 * @version 1.1
 */
public class Test1 {
	/** フィールドのテスト */
	private String str = "abc";

	/**
	 * メソッドのサンプル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;
	}
}

 

2.プロジェクトまたはファイルを右クリックし「エクスポート」から「JavaDoc」を選択し次へを押して行き出力します。

 

3.index.htmlが出力されるのでブラウザで開くとHTML形式で確認できます。

 

クラスの上にあるコメント

@author 作成者
@version ソースコードのバージョン
/**
 * Test1クラスのサンプルです<br>テスト改行1<br>
 * テスト改行2
 * テスト改行3
 * @author testuser
 * @version 1.1
 */

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

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

 

メソッドの上にあるコメント

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

@paramは、メソッドの引数の説明です。このメソッドには2つ引数があるので2行で書きます。
書き方は、「@param 引数 説明」で、引数と説明の記述が必要です。

引数が2つない場合、Javadoc生成時にエラーが発生します。(エラー: @param nameが見つかりません)

@returnは、メソッドの戻り値の説明です。
@throwsは、メソッドが投げる例外の説明です。
書き方は、「@throws 例外 説明」で、例外と説明の記述が必要です。

引数が2つない場合、Javadoc生成時にエラーが発生します。(エラー: 予期しないテキストです)

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

 

フィールドの上にあるコメント

	/** フィールドのテスト */
	private String str = "abc";

フィールドの説明は、以下のように表示されます。

 

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

@deprecated 説明
  /**
   * メソッドのサンプル2です
   * 
   * @deprecated 処理なし
   * @return intを返します
   */

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

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

 

その他のJavadocタグ

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

 

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

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

JavaDoc出力時に上記エラーが発生する場合は
「Javadocの生成」ダイアログの「追加のJavadocオプション」に以下を記述します。

-encoding UTF-8
-charset UTF-8

このダイアログの出し方は、プロジェクトやコードを右クリックし「エクスポート」からJavaDocを選択し「次へ」を3回押します。

excel20_2

関連の記事

Eclipse Javadocの生成方法

△上に戻る