javadocでのAPIドキュメント作成

更新:2003/12/5

javadocのでのAPIドキュメント作成

JAVAでプログラミングする場合、多くがWeb形式のJAVA_APIリファレンスを見ながら作業するでしょう。
自分の作ったプログラムでも、このAPIリファレンスと同じ書式のjavadocを手軽に作成することができます。
javadocを作成するには、各プログラムのソースコードに決められた書式でコメントを記入、javadocコマンドでWeb形式のAPIリファレンスを自動生成してくれます。

javadocで作成されるドキュメントで必要な情報は、大まかに以下の物があります。
package----ClassがPackageに属する場合は、Package概要を明記する。
class------Classの概要、使用方法、作者、関連クラスなどを明記する。
method-----Methodの概要、引数、返り値、例外などを明記します。

classとmethodセクションは、それぞれのソースコード内に決められた方法によりコメントを記述します。
packageについては、ソースコードを保存してあるディレクトリ(パッケージ名のディレクトリ)に、package.htmlファイルを作成します。

サンプルコードを使用し説明します。
サンプルコードは、Package sampleに属す、DocTestクラスです。

A)javadoc 用のコメントを作成します。
1.パッケージ概要
Package概要は、ソースコードを保存してあるディレクトリ(パッケージ名のディレクトリ)に、package.htmlファイルを作成します。
package.htmlの内容は、このパッケージがどんなクラスの集合化を簡素に記入します。
sample/package.html
<HTML>
<BODY>
JAVA DOC作成用サンプルクラスファイルが含まれています。 
</BODY>
</HTML>

2.クラスとメソッド用に、ソースコードへの記載方法
クラスセクション
import文の下にあるのが、クラスの説明になります。
１行目は、クラスの概要説明にも使用されます。
２行目以降は、クラスの詳細説明です。
@seeで関連するクラスを記載
@authorで作成者を記載
@versionでこのクラスのバージョンを記載
class宣言文の下に、クラス変数fileの説明が記載してあります。

メソッドセクション
書くメソッドの最初に、javadocを書いて行きます。
１行目は、メソッドの概要説明にも使用されます。
２行目からはメソッドの詳細説明です。
必要に応じて、
@paramで引数の説明
@returnで返り値の説明
@throwで例外クラスと例外の内容を説明

＊DocTestサンプルコード

package sample;

import java.io.IOException;

/**<PRE>
*このクラスは、javadocの説明をするためのサンプルクラスです。
*このクラスに実装されているメソッドは、javadocの説明をするために書かれています。
*そのため、実際に動作するメソッドはありません。
*@see java.io.File
*@author Tomoya Sakurai
*@version 1.0
</PRE>*/
public class DocTest{

 /**
 *File型の値を格納する変数
 */
 private File file;

 /**
 *インスタンスを作成します。
 */
 public DocTest(){
 }

 /**
 *メソッドtest1です。 
 *引数や返り値はありません。
 */
 public void test1(){
 System.out.println("Hello");
 }

 /**
 *メソッドtest2です。 
 *引数があり、例外を発生することがあります。 
 *@param path ファイルを作成するPATHを指定
 *@throws IOException ファイルが生成できなかった場合
 */
 public void test2(String path) throws IOException {
 file=new File(path);
 }

 /**<PRE>
 *メソッドtest3です。
 *返し値があり、例外が発生することがあります。
 *@return 作成されたファイルオブジェクトを返します。
 *@throw IOException ファイルが生成できなかった場合
 </PRE>*/
 public File test3()throws IOException{
 return file;
 }
}

Capture.1 javadocコメントを書くとの注意点
＊"/**"から"*/"までが javadoc に反映されます。
＊1行目は、クラスやメソッドの概要説明にも使用されます。
＊コメントは、HTMLで処理されますので、改行コード が必要ですが、@***などのタグは自動で改行されます。
＊<PRE>< /PRE> 間にあるコメントは、そのままの状態で表示されます。(インデントや改行コードは必要ありません。)

javadocの主なタグ一覧

タグ名	JAVA Version	説明
@author	1.0	クラスの作成者情報を記載
@deprecated	1.0	推奨されないAPIであることを示す
@throw	1.0	発生する例外クラスを指定
@param	1.0	メソッドの引数の説明
@return	1.0	メソッドの返り値の説明
@see	1.0	他のAPIを参照する場合に記載
@serial	1.2	直列化されたフィールドの説明
@sesrialData	1.2	直列化された状態でのデータ型と順序を記載
@since	1.1	導入されたバージョンを記載
@version	1.0	バージョンを記載

B)javadoc コマンドで、javadocを作成します。
まず、javadocの作成されるディレクトリを用意します。
今回は、
$HOME/APP/sample/DocTestの javadocを、$HOME/APP/doc/に作成します。
%cd $HOME/APP/doc
%javadoc -author -version -sourcepath $HOME/APP sample
これで、$HOME/APP/doc以下にjavadocが生成されます。
ブラウザで、$HOME/APP/doc/index.htmlを開き、確認してください。

Capture.2 javadocコマンドの書式

コマンド	説明
javadoc [-オプション] [パラメータ]	javadocファイルを作成
オプション	説明	オプションパラメータ
-author	作成者情報を表示します
-version	Version情報を表示します
-private	Privateメソッドも含めて表示します
-sourcepath	ソースディレクトリを指定	ソースディレクトリ
-encoding	ソースファイルのエンコードを指定	EUC-JP,SJISなど
-d	生成先ディレクトリを指定	PATH
-docencoding	作成されたjavadocのエンコードを指定	EUC-JP,SJISなど
-charset	生成されたjavadocのcharset	EUC-JP,SJISなど
パラメタ	説明
パッケージ名で指定	複数の場合は、スペースで区切る
ソースファイルを指定	複数の場合は、スペースで区切る

Producted by Tomoya Sakurai