14．Javadoc入門
当コーナーはJavaの基本的な事項を紹介していくものです。
HelloWorldJavaDoc.java
Javadocとはクラス、メソッドの説明時に使用するドキュメンテーションコメントを 指します。ドキュメンテーションコメントは”/**”～”*/”の間にクラス・メソッドの説明や引数、戻り値の説明を記入します。
またドキュメンテーションコメント以外のコメントでは、インプリテーションコメントがあります。 インプリテーションコメントは、”//～”や”/*～*/”のようにソースの説明時に使用されます 以下の表では、主に使用されるコメントを紹介します。
| コメント | 記述例 | 説 明 |
|---|---|---|
| //… | //サンプルコメントです | //からコメント扱いになりますが一行のみです |
| /*…*/ | /*サンプルコメントです*/ | /* を先頭に、*/ までがコメントの範囲になり、複数行に渡って記述できます。 |
| /** * */ |
/** *サンプルコメントです */ |
/** を先頭に、*/ までがコメントの範囲になり、複数行に渡って記述でき, Javadocに使用されます。 |
Javadoc内では、コメントを記入する際にクラスやメソッドの役割を示すためにタグを使用します。
使用するタグは以下の種類があります。
| タグ名 | 説 明 |
|---|---|
| @author | クラスの作成者情報を記載 |
| @param | メソッドの引数の説明 |
| @return | メソッドの返り値の説明 |
| @throw | 発生する例外クラスを指定 |
| @see | 他のAPIを参照する場合に記載 |
| @deprecated | 推奨されないAPIであることを示す |
| @serial | 直列化されたフィールドの説明 |
| @sesrialData | 直列化された状態でのデータ型と順序を記載 |
| @since | 導入されたバージョンを記載 |
| @version | バージョンを記載 |
Javadoc記入時の注意点
注意点としては、記載の際は宣言するソースレベルにインデントします。 また、Javadocはクラス・メソッドの説明を記載しているために対応する宣言の直前に置く必要があります。 例としては以下のようになります
クラス宣言時
/**
* HelloJavaは、HelloJavaを表示するクラスです。
* @author アイオス哲郎
*
*/
public class HelloJava{ …
………
……
System out println(“HelloJava”)
}
メソッド宣言時
/**
* searchDbは、検索用のメソッドです。
* @param con コネクションです。
* @param tradebean 入力フォームに入力された文字が入っています。
* @return 検索結果を格納したリストです。
* @throws SQLException SQL実行時に起きりうる例外
* @throws IOException ファイル入出力時に起きりうる例外
*/
public List searchDb(Connection con,TradeInfoBean tradebean)
throws SQLException,IOException{
…//何らかの処理
}
/**
* listDbは、表示用のメソッドです
* @param searchResltList 検索結果を格納したリストです。
*/
public void listDb(List searchResltList){
…//何らかの処理
}
リファレンスマニュアル作成（コマンドプロンプト編）
今回はリファレンスマニュアル作成を行なっていきます。
リファレンスマニュアルとは言語使用を一覧に したものをさしますので、ここでの意味としてはJavaの言語使用一覧を言います
以下のテスト用のJavaソースを使用してリファレンスマニュアルを作っていきたいと思います。
/**
* JavaDocテスト用クラスです。
* @author アイオス太郎
* @version 1.0
*/
public class HelloWorldJavaDoc {
/**
* メインメソッドです
*/
public void main(String[] args){
System.out.println(“Hello,Java”);
}
}
コマンドを用いて、先ほどのファイルを”javadoc -d docs HelloWorldJavaDoc.java”というコマンドを用いると以下のように リファレンスマニュアルが生成されていきます。
コマンド上で生成されたのが確認できましたら、HelloWorldJavaDocのファイルと同じ場所に
“docs”というフォルダが 生成されます
その中の”index.html”を選択すると、リファレンスマニュアルが確認できます。
HelloWorldJavaDocのリファレンスマニュアル
リファレンスマニュアル作成（エクリプス編）
今回はコマンドプロンプトで行なったリファレンスマニュアル作成をエクリプス上で行ないます。使用ソースは先ほど 使用したソースを引用して、リファレンスマニュアル作成を行ないます。
HelloWorldJavaDoc.java
ソースに”HelloWorldJavaDoc”を入力したら、ファイル→エクスポート→Javadocと選択すると以下の画面になります。
以下の画面になりましたら「Javadocコマンド」に(j2sdkをインストールしたフォルダ)\bin\javadoc.exeを選択し「javadocが生成される型」をチェックして、終了を押すと、リファレンスマニュアルが生成されます。
コンソール上でリファレンスマニュアルが生成されています
HelloWorldJavaDocのリファレンスマニュアル