簡単な Javadoc の書き方


[07/03, 2003 H.Aman]
Java メモへ戻る

  1. はじめに

    2. Javadoc は Java2 SDK に付属しているドキュメント生成ツールである． これは Java ソースプログラムから特定の情報を抽出し， そのドキュメントを HTML 形式で生成する． Java API がその代表例である．

    まず，コメントを一切書いていない Java ソースプログラム Foo.java を Javadoc で処理してみる． すると図 1 のようなメッセージが表示され，12 個のファイルが生成される． 

    $ javadoc Foo.java
ソースファイル Foo.java を読み込んでいます...
Javadoc 情報を構築しています...
標準 Doclet バージョン 1.4.1

constant-values.html の生成
全パッケージとクラスの階層ツリーを作成しています...
全パッケージとクラスのインデックスを作成しています...
overview-tree.html の生成
index-all.html の生成
deprecated-list.html の生成
全クラスのインデックスを作成しています...
allclasses-frame.html の生成
allclasses-noframe.html の生成
index.html の生成
packages.html の生成
Foo.html の生成
package-list の生成
help-doc.html の生成
stylesheet.css の生成
    図 1．javadoc の使用例

    生成された index.html をブラウザで開くと このように なる．
    デフォルトでは public もしくは protected なメソッド・フィールド・コンストラクタが抽出され， ドキュメントに掲載される．
    ソースプログラム中の適切な位置に ドキュメンテーションコメント と呼ばれるコメント文を挿入することで Java API のようなドキュメントが生成される．

  2. ドキュメンテーションコメント

    3. ドキュメンテーションコメントとはコメント文の一種である．
    その記述は /** で始まり */ で終わる．

    ドキュメンテーションコメントをメソッド宣言の 直前に 挿入した場合，Javadoc はそれを (直後に宣言してある) メソッドの説明文としてドキュメントに掲載する．
    クラス宣言，インタフェース宣言，フィールド宣言，コンストラクタ宣言に対しても同様である．

    ドキュメンテーションコメントでは， その API の利用者にとって有用な情報を記述すべきである． 内容としては，目的・機能・使用法等を明記するとよい． その際，以下で紹介する特殊タグが役立つ． なお，ドキュメンテーションコメントの記述は HTML 形式のドキュメントに転用されるので，コメント中に HTML タグを挿入してもかまわない．

    以下ではドキュメンテーションコメント用の特殊タグをいくつか紹介する． これらの詳細や紹介していないタグについては Sun Microsystems のページ を参照されたい．

    • @param タグ

      • メソッドやコンストラクタの引数の説明に使用する．
      書式は表 1 の通りである．

      表 1．@param タグの書式 
        @param  引数名  引数の説明

      例えば，メソッドの説明として図 2 のようなドキュメンテーションコメントが書ける． 

      /** 
 * XXX 用の表示データを設定する
 *
 * @param  aData  表示データ
 */
public void setData( int aData )
{
   ...
      図 2．@param タグの使用例

    • @return タグ

      • メソッドの戻り値の説明に使用する．
      書式は表 2 の通りである．
      javadoc コマンドに 表 2．@return タグの書式 
        @return  戻り値の説明

      例えば，メソッドの説明として図 3 のようなドキュメンテーションコメントが書ける．

      javadoc コマンドに 

      /** 
 * XXX 用の表示データを返す
 *
 * @return  表示データ
 */
public int getData( )
{
   ...
      図 3．@return タグの使用例

    • @see タグ

      • 関連項目へのリンクを示す．
      ここでは他のクラスやメソッドを指定できる． web ページへリンク（<a>〜</a>）を書いてもよい．
      表 3．@see タグの書式 
        @see  関連項目

      図 4 は他のクラス，メソッド及び Web ページをそれぞれ関連項目とした例である． 

      /** 
 * ....................
 * ....................
 * 
 * @see  java.util.Vector
 * @see  java.lang.Integer#parseInt
 * @see  <a href="http://www.foo.bar.ac.jp/">参考ページ</a>
 */
public int getData( )
{
   ...
      図 4．@see タグの使用例

    • @exception タグ

      • コンストラクタやメソッドで発生しうる (throws に列挙してある) 例外の説明に使用する．

      表 4．@exception タグの書式 
        @exception  例外クラス名  説明(例外発生の条件等)  

      /** 
 * ....................
 * ....................
 * 
 * @exception  java.lang.ArithmeticException  指定されたデータに対応できない場合に発生
 */
public void setData( int aData )
{
   ...
      図 5．@exception タグの使用例

    • @author タグ， @version タグ

      • それぞれ API の著者とバージョンの指定に用いる．

      表 5．@author タグ，@version タグの書式 
        @author  著者
  @version  バージョン

      CVS でバージョン管理している場合は $Revision$ という文字列が自動的にリビジョン番号になるので， これを @version タグで指定してもよい．

    例えば，ドキュメンテーションコメントを記述した このような Java プログラムを Javadoc で処理すると， このような ドキュメントが生成される．

  3. javadoc コマンドの使い方

    4. 基本的には Java ソースファイル名をコマンドライン引数にして javadoc コマンドを実行すればよい． このときファイル名は複数個（空白で区切る）指定できる． ワイルドカード（例えば *.java）で指定してもよい． 

     $ javadoc  Foo.java  Bar*.java
    図 6．javadoc の使用例 ($ はプロンプト)

    図 6 のように実行するとカレントディレクトリにドキュメントが生成される．
    他のディレクトリへ出力したい場合は -d オプションで出力先ディレクトリを使用する．(図 7) 

     $ javadoc  -d /home/aman/docs  Foo.java  Bar*.java
    図 7．javadoc の使用例

    プログラムをパッケージ化している場合は， ソースファイル名の代わりにパッケージ名を指定することもできる． その場合，そのパッケージのソースファイルのパスを -sourcepath で指定する．(図 8) 

     $ javadoc  -sourcepath /home/aman/tmp  jp.ac.ehime_u.cs.mypack
    図 8．javadoc の使用例

Java メモへ戻る