Javadocの書き方 - ぐるぐる～

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

Javadocとは

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

書き方

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

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

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

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

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

クラスやメンバ等の概要

クラスやメンバ等の概要*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を指定すればいい。
「スタイルシート」はデフォルトでいい。何かこだわり等があるならどうぞ。
次へ。