１４、JavaDocの生成

１４、JavaDocの生成

作成者：Fumitaka Makino

更新日:2003-04-11 19:52

・JavaDocの書き方

歴史のないJava言語の急速な普及には、「JavaDoc」という洗練されたドキュメント環境が大きく影響しています。そのいつも利用しているJavaDocは実は簡単に生成できます。ソースごとに対して記述しているコメント文を、いくつかの簡単な文法に従って記述すればそれがJavaDoc用のコメントとなります。当然ですがJavaDocはクラスの再利用のためのプロセスの大事な１ステップです。どんなに優れた再利用性を持つクラスでもソースを追わないと利用法がわからないのでは誰も「再利用」してくれません。ソースコードを記述する上で毎回毎回JavaDocを記述するのは、はっきりといって非常に骨の折れる作業ですが必ず記述してください。

では具体的にはどのように記述すればよいのでしょうか？下記のソースファイルとJavaDocを見て下さい。

AddressDataクラス → ソースファイル、JavaDoc

２つを見比べてみるとJavaDocに掲載されている文章が、ソースファイル中にコメントとして記述されているのがわかると思います。JavaDoc用のコメントは下記のような決まりに基づいています。

クラス、フィールド、メソッドの宣言文の直前に記述する。
JavaDoc用のコメント文は「/**」で始まり「*/」で終わる。
文章はHTML形式で記述する。（つまりタグが有効である）
＠で始まる特別な文字列（タグと呼ばれることもある）でパラメーターや戻り値の説明を記述する。

まずは最低限必要なJavaDocの記述をしてみましょう。それではクラスの宣言部分のJavaDocを見てみましょう。

例：「AddressData」クラスのサンプル

/**
　　アドレス情報を表すクラス
　　@author Fumitaka Makino
　　@since J2SDK 1.2
　　@see AddressBook AddressBookクラス
*/
public class AddressData {

・・・

}

当然クラスの説明を行うJavaDocなのでクラスの宣言文の直前に記述します。「/**～*/」の形式でコメントしてある部分がJavaDocとして扱われ、「アドレス情報を表すクラス」というのが説明の本文となります。また＠から始まっている部分は作成者や導入されたバージョンなど特定のテンプレートの値として扱われます。

例：生成されたJavaDocの一部分

では次にフィールド部分を見てみましょう。説明のみが記述してあります。今回はプライベートフィールドなため通常のドキュメントには反映されませんが、ここで記述したコメントがフィールドの説明として扱われます。ただJavaDocを生成するオプションの指定によってはプライベートフィールドであってもドキュメントに掲載されます。

例：「AddressData」クラスのサンプル


	・・・　　　　/** 　　　　氏名　　*/ 　　private String name = null; ・・・

最後に一番重要なメソッド、コンストラクタ部分を見て下さい。

例：「AddressData」クラスのサンプル


	・・・　　　　/** 　　　　アドレスデータのコンストラクタ　　　　@param String 名前　　　　@param String 電話番号　　　　@param String 住所　　/ 　　public AddressData( String sname , String stel , String saddr ){ 　　　　　　　　name = sname; 　　　　tel = stel; 　　　　addr = saddr; 　　　　　　} 　　　　/* 　　　　名前をセットします。　　　　@param String 名前　　/ 　　public void setName(String str){ 　　　　name = str; 　　} 　　　　/* 　　　　名前を取得します。　　　　@return String 名前　　*/ 　　public String getName(){ 　　　　return name; 　　} 　　・・・

基本的にコンストラクタとメソッドの部分の記述方法は同一です。また機能について説明する部分に関してもクラスやフィールドと同じです。しかしメソッドには引数と戻り値があり、これらの説明を明確にする必要があります。そこで引数については第一引数から順番に「@param」を用いて型を記述し、さらにその値の説明を記述します。また戻り値に関しても同様に「@return」を用いて型を記述し、その値の説明を記述します。またここにはありませんが「@throws」や「@exception」によりスローされる可能性のある例外についての説明を記述することもできます。JavaDocやJavaDocタグの機能詳細は、J2SDKのドキュメントの一部として以下に詳しく掲載されていますのでタグの使い方などを調べる場合には必ず参照しましょう。

http://java.sun.com/j2se/1.4/ja/docs/ja/tooldocs/solaris/javadoc.html

http://java.sun.com/j2se/1.4/ja/docs/ja/tooldocs/solaris/javadoc.html#javadoctags

・JavaDocの生成方法

ではソースファイルに対して追加したJavadocのコメントを、実際にHTMLのJavadocとして参照できるようにしましょう。J2SDKにはjavacやjavaコマンドのように利用するjavadocというコマンドが存在します。このjavadocの利用法はjavacなどと非常に似通っているので難しくはないと思います。細かい使い方は上記のリンク先のドキュメントなどを参照してほしいのですが一般的にはソースのある場所で、コマンドラインから下記のように実行します。すると実行した場所で該当するソースファイルのjavadocが生成されます。

javadoc *.java

ただこれだけだと非常に不便なので、HTMLの排出先を現在いるディレクトリのapidocというディレクトリの下に書き出すようにしてみましょう。その場合は

javadoc -d apidoc *.java

というように-dオプションを用いてドキュメントの排出先ディレクトリを指定することができます。その他にも別なAPIのドキュメントと連動するようにしたり、privateフィールドのドキュメントも生成したりとさまざまなオプションがあります。ちなみにこの講座で利用しているサンプルソースのjavadocは以下のようなコマンドで生成しています。時間があれば何をやっているのか調べてみましょう。

javadoc -d apidoc -author -linksource -link http://java.sun.com/j2se/1.4/ja/docs/ja/api/ *.java

↑上へ目次へ戻る