Javadocの書き方

Javadoc、活用していない人も結構いると思うけど、なんとなく使っている人も結構いると思う。そこで、今回はJavadocについてまとめてみます*1
Eclipse*2の使用を前提としてるんで、その辺は注意してください。

Javadocとは

Javadocとは一般に、JavaのソースファイルからJavadoc形式のコメントを抜き出し、ドキュメントを生成するツール、もしくはそのコメント自体、もしくは出来上がったドキュメントを指す。
が、コメント自体は本来、ドキュメンテーションコメントと呼ぶべき*3

書き方

詳しくは、Oracle Technology Network for Java Developersを見てもらえばいいとして、ここでは基本的なことのみを説明する。

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

ドキュメンテーションコメントとは、下のように/** 〜 */ではさまれた部分を指す。

/**
 * HogeクラスのJavadoc。先頭にある*と、それ以前の空白(スペースやタブ)は無視される。
 */
public class Hoge {
}

ドキュメンテーションコメントはHTML形式で記述しなければならない。よって、&や<、>は&amp;、&lt;、&gt;と記述しなければならない。

クラスやメンバ等の概要

クラスやメンバ等の概要*4は、ドキュメンテーションコメントの一行目が使用される。
よって、ドキュメンテーションコメントの一行目はよく考えて記述すること。

Javadocタグ

Javadocタグには、HTMLと同様、ブロックタグとインラインタグに分類される。
これらの違いは、形式によって判別できる。ブロックタグの形式は@tag、インラインタグは{@tag}となる。


Javadocタグの詳細はJavadocタグを参照してもらうとして、代表的なタグだけ説明する。

タグ名 意味、使い方
@author トップレベルのクラス*5の作者を表す。
@deprecated 非推奨を表す。代替手段を@seeで用意するとよい。詳細は、Oracle Technology Network for Java Developersと、@deprecated参照
{@inheritDoc} 上位階層のクラス、インターフェイスからドキュメントをコピーする。
{@link} クラスやメンバに対してリンクを貼る。{@link package.class#member label}のように記述する。形式は@see参照
{@literal} この中に記述したテキストを、リテラルとして扱う。つまり&等、エスケープしなくてもJavadocがエスケープしてくれる。
@param メソッドの引数、または型引数*6の説明を記述する。形式は、@param pram-name description*7
@return メソッドの戻り値について記述する。
@see 関連項目を表す。形式は@see参照
@throws メソッドからスローされる可能性のある例外を記述する。形式は@throw except-name description
パッケージコメントファイル

パッケージに対してコメントをつけたい場合は、.javaファイルとともにpackage.htmlをパッケージ内に置く。
このファイルの内容はドキュメンテーションコメントだが、/** 〜 */で囲ってはいけない。さらに、行頭の*も禁止されている。


ここでも最初の文が概要となる。

概要コメントファイル

アプリケーション、またはパッケージセットに対するコメントをつけることもできる。
ファイル名もパスも任意だが、通常はファイル名をoverview.htmlとして、ソースツリーの最上位に置く。
パッケージタグと同様、内容はドキュメンテーションコメントで、/** 〜 */で囲ってはいけない、行頭の*が禁止という点も同じである。


ここでも最初の文が概要となる。

Javadocタグを使用できる場所

Javadocタグを使用できる場所は、要素によって異なる。
詳細はタグを使用できる場所参考。

作り方

パッケージ・エクスプローラとかで、右クリック、エクスポートから。
ダイアログが開いたら、Javaの中にあるJavadocを選択、次へ。


もし、「Javadocコマンド」が空なら、「構成」からjavadocコマンドを選択*8
Javadocが生成される型の選択」は、Javadoc作りたいクラス*9を選べ、ということ。プロジェクトにチェックを入れちゃえば問題なし。テスト用のクラスがあるなら、それははずしてもOK。
「次の可視性を持つメンバーにJavadocを作成」は、選択した可視性を含め、よりゆるい可視性のクラスやメソッド等についてJavadocを生成する。まぁ、下に解説が出るからそれを参考に。
ドックレットは「標準ドックレットを使用」で問題なし。出力等をカスタマイズしたい場合のみ、「カスタム・ドックレットを使用」を選ぶ。
「宛先」はJavadocが生成される場所なんで、生成した居場所を指定するだけ。
次へ。


「文書タイトル」はJavadocのタイトルで、指定しなかったら「概要」、とかそんな感じ。
「基本オプション」は全部チェック入れとくことをおすすめする。
「これらのタグの記述」は、訳しすぎ。@作成者は@author、@バージョンは@version、@使用すべきではないは@deprecatedがJavadoc中に現れた場合、Javadocとして出力するかどうかを指定する。基本的には全部チェックしておく。
「リンク生成が必要な、参照されたアーカイブおよびプロジェクトを選択」は、@linkとかのリンクを生成するタグを使用したとき、外部のプロジェクト等へもリンクを貼れるようにするためのもの。rt.jarは標準ライブラリの入ったアーカイブなので、選択しておくことをおすすめする。びっくりマークが出ているなら、Javadocの場所が設定されていないので、「参照」からindex.htmlがあるフォルダ、ディレクトリを選択する*10。ローカルに当該Javadocがなくても、インターネット上のURLも使えるので、http://java.sun.com/j2se/1.5.0/ja/docs/ja/api/index.htmlを指定すると、ネットのドキュメントにリンクされる*11サーブレット等、J2EEの場合*12は、ローカルになければ同じくhttp://java.sun.com/j2ee/sdk_1.3/ja/techdocs/api/index.htmlを指定すればいい。
スタイルシート」はデフォルトでいい。何かこだわり等があるならどうぞ。
次へ。


「概要」は、概要コメントファイル(overview.html等)があれば指定する。
あとはJavadocコマンドに渡す引数なんで、オプションを参考にどうぞ。
終了。

これで指定したフォルダにJavadocが出来るはず。index.htmlをブラウザで開くとちゃんと見れる、はず。

最後に

Javadocはまめに作らないと、どんどんたまっていくので、書くと決めたら一つのクラスを作ったらもう書いちゃってください。もしくは作りながら書くか。でないと、さぼってしまいがちなんで。

*1:基本的に[http://java.sun.com/j2se/1.5.0/ja/docs/ja/tooldocs/windows/javadoc.html:title]を読めば載ってるんですけどね。

*2:Eclipse3.2、しかも日本語化済み、ということで

*3:というか、そう呼んでください。商標の侵害に当たります。[http://java.sun.com/j2se/1.5.0/ja/docs/ja/tooldocs/windows/javadoc.html#comments:title=参考、ソースコードへのコメントの挿入]

*4:〜の概要というテーブル

*5:もちろんインターフェイスや列挙型も含む。

*6:ジェネリクスのEとかKとかVとかのこと

*7:型引数の場合は@param <type-name> description

*8:Windowsならjavadoc.exeのパスを教えてあげればOK。普通は%JAVA_HOME%\bin\javadoc.ext

*9:もちろんインターフェイス、列挙型も。つまり、.javaファイル

*10:index.html自体を選択してはダメ

*11:自分用ならローカルでもいいけど、そうでないならネット上のドキュメントを参照しといたほうがいいかも

*12:servlet-api.jar等