JavaのJavadocの書き方のサンプルです。(確認環境:Java, Eclipse, STS)
目次
| サンプル | Javadocとは |
| Javadocを作成する | |
| クラス上のコメント / メソッド上のコメント / フィールド上のコメント | |
| メソッドを非推奨にした場合 @deprecated | |
| エラー: この文字は、エンコーディングMS932にマップできません |
Javadocとは
- Javadocとは、Javaのソースコードから生成されるHTML形式のコードの仕様書です。
改行の<br>等も使用できます。 - Eclipseで、/** を入力してエンターキーを押すとJavadoc形式で自動入力されコメントになります。コメントの修正も可能です。
- コメントをこの形式にしておくと、Javadocにコメントが反映されます。
Javadocのコメントの作り方
| /** を入力してエンターキーを押す |
Javadocを作成する
１．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;
}
}
２．プロジェクトまたはファイルを右クリックし「エクスポート」から「JavaDoc」を選択し次へを押して行き出力します。
３．index.htmlが出力されるのでブラウザで開くとHTML形式で確認できます。
クラスの上にあるコメント
| @author 作成者 @version ソースコードのバージョン |
/**
* Test1クラスのサンプルです<br>
* テスト改行1<br>
* テスト改行2 テスト改行3
*
* @author testuser
* @version 1.1
*/
public class Test1 {HTMLタグの<br>を使用しています。改行されます。
注：スラッシュ付きの<br />はエラーになります。(エラー: 自己終了要素は使用できません)
@authorは、作成者です。
@versionは、ソースコードのバージョンです。
クラスの説明は、以下のように表示されます。
メソッドの上にあるコメント
| @param 引数名 説明 @return 説明 @throws 例外名 説明 |
/**
* メソッドのサンプル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;
}@paramは、メソッドの引数の説明です。このメソッドには2つ引数があるので2行で書きます。
書き方は、「@param 引数 説明」で、引数と説明の記述が必要です。
| 引数が2つない場合、Javadoc生成時にエラーが発生します。(エラー: @param nameが見つかりません) |
@returnは、メソッドの戻り値の説明です。
@throwsは、メソッドが投げる例外の説明です。
書き方は、「@throws 例外 説明」で、例外と説明の記述が必要です。
| 引数が2つない場合、Javadoc生成時にエラーが発生します。(エラー: 予期しないテキストです) |
メソッドの説明は、以下のように表示されます。
フィールドの上にあるコメント
/** フィールドのテスト */
private String str = "abc";フィールドの説明は、以下のように表示されます。
メソッドを非推奨にした場合 @deprecated
| @deprecated 説明 |
/**
* メソッドのサンプル2です
*
* @deprecated 処理なし
* @return intを返します
*/
int calc2() {
int c = 0;
return c;
}@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回押します。
関連の記事