S-JIS[2008-02-22/2010-04-28] 変更履歴

Javadoc

Javaの特殊なコメント。
コメントの書き方がルール化され、それを元に説明書を作成することが出来る。

クラス・メソッド・フィールド（変数）にJavadocコメント（説明）を付けられるので、それらの説明が見られることになる。

Javadocと言った場合、「Javadocコメントの書き方」と、それを元に生成された「API仕様（HTML文書）」のいずれかを指すことが多い。
後者は、Javaの（標準ライブラリーの）API仕様が有名。→Javadocの読み方（入門者向け）

Javadocの生成方法

Javadoc生成用のコマンドを使って、JavaのソースファイルからHTMLを生成する。

• javadocコマンド … これが一番基本
• Eclipseを使ったJavadoc生成 … お手軽に作りたいなら、これが一番楽
• Antのjavadocタスク（javadocタグ） … 何度も自動生成したいなら、これが一番便利

いずれの方法でも、対象となるソースファイルの数が多ければ 生成にそれなりの時間がかかる。

→ひしだまが自分で生成したJavadoc

javadocコマンド

javaコンパイラー（javac）と同じ場所にjavadocというコマンドが置かれている。
これを実行すればJavadocが生成できる。

javadoc 生成対象スコープ -d 生成場所 -sourcepath ソースファイルの先頭ディレクトリー パッケージ名

> cd \workspace\project
> javadoc -public -d doc -sourcepath src jp.hishidama.sample jp.hishidama.sample2

詳細なオプションは「javadoc -help」でヘルプが見られるので、それで確認。

指定したパッケージの中にソースファイルが1つも無かったらエラーになる。
パッケージ名にはワイルドカード（*）は使えない。
また、指定したパッケージの下の階層のパッケージは対象外なので、1つ1つ個別に指定してやる必要がある？
→したがって、数が増えたらEclipseやAntを使う方が便利。

• Solaris版のリファレンスガイド
• Windows版のリファレンスガイド

Javadocの書き方（ルール）

以下のような感じ。

	/**
	 * 文字列結合.
	 * <p>
	 * 2つの文字列を結合する。<br>
	 * ただしnullの場合は空文字列として扱う。
	 * </p>
	 * 
	 * @param str1 文字列（null可）
	 * @param str2 文字列（null可）
	 * @return 結合した文字列（必ずnull以外）
	 */
	public static String concat(String str1, String str2) {
		if (str1 == null) {
			if (str2 == null) {
				return "";
			} else {
				return str2;
			}
		} else {
			if (str2 == null) {
				return str1;
			} else {
				return str1 + str2;
			}
		}
	}

/**

Javadocコメントは「/**」で始め、「*/」で終わる。
複数行にまたがる場合は、間の各行の先頭に「*」を置く。（置かなくても大丈夫ではあるが、普通は置く。置いた方が揃っていて綺麗だし。手作業だと面倒だけど、Eclipseのソース整形機能を使えば勝手に入れてくれる）

	/**
	 * サンプル
	 */
	public static final int SAMPLE = 123;

一行だけのJavadocコメントを書くことも可能。[2004-06-19]

	/** サンプル */
	public static final int SAMPLE = 123;

要は普通のコメント「/*」に対してアスタリスク「*」が1つ増えただけ。
とは言っても「//*」というのはJavadocコメントにはならない＾＾；

ピリオド

「/**」直後の最初の文は、生成したJavadocの見出し（メソッド一覧やクラス一覧）に使われる。

“最初の文”の判断は、最初のピリオド「.」＋空白文字（改行やブランク）が来るまで。
もしくは最初のブロックタグ（@author等のJavadocタグ）が来るまで。

日本語なら句点「。」も文の終わりとして欲しいところだが、javadocコマンドはそこまで対応してないわなぁ。
もっと言えば、ただ単に改行してたら終わりと見なしてくれる方がいいんだけど…メソッド名やクラス名を書きたいだけの場合でもピリオドを付けなきゃいけないので、生成されたJavadocにピリオドが付いててくどくなるんだよな〜。

HTMLタグ

Javadocコメントの説明文の中にはHTMLのタグを使うことが出来る。
Javadoc生成時には（基本的に）書いた文章はそのままHTMLのソースになるので、逆に、改行したい場合はbrタグとかを書いておく必要がある。

	/**
	 * 説明文です。<br>
	 * 改行タグを入れないと、	←ここはJavadoc生成時に改行されない
	 * 生成したときに改行されないよ。
	 */

codeタグやpreタグを使って そのメソッドの使い方のサンプルを入れたりすると、見る側からすると分かり易くていいだろう。
しかしpreタグはEclipseのソース整形機能を使うと勝手に改行されたりインデントが無くなったりするのでちょっと不便。

→コードは@codeタグを使うものらしい （JDK1.5以降）

Javadocタグ

アットマーク「@」で始まる特定のキーワードはJavadocタグと呼ばれ、特殊な扱いをされる（定められた情報を持つ）。
それぞれのJavadocタグは書ける場所が決まっている。主にパッケージ・クラス・メソッド （コンストラクター）・フィールド（メンバー変数）のいずれか、またはその組み合わせ。

Javadocタグはたいてい後ろに何らかの説明文を書くが、ここにHTMLのタグを入れることも可。
また、説明文は複数行にまたがってよい。次のJavadocタグが来るまで、1つの文章（HTML）として扱われる。
（つまりJavadocコメント上での改行は自由だが、生成されたJavadocを改行した状態にしたいならbrタグ等が必要だということ）

• Solaris版のJavadocタグ一覧
• Windows版のJavadocタグ一覧

“{@タグ}”という形式のJavadocタグをインラインタグと言う。これは文章中のどこにでも自由に置くことが出来る。
“@タグ”という形式のJavadocタグをブロックタグと言う。これは独立したブロック（説明箇所）が作られる。

コメントファイル

Javadocコメントは主にソースファイル内に書くが、パッケージの説明や全体の概要などの“ソースファイルには書けないもの”は別ファイルに用意する。

留意事項

JavadocコメントとJavadocコメントの間のコメント

例えばメソッド本体（だけ）をコメントアウトすると、Javadoc用コメントが浮いてしまって変なJavadocが生成される… [2003-07-06]

	/**
	 * 説明１
	 */
/*	public int func1() {
	}
*/
	/**
	 * 説明２
	 */
	public int func2() {
	}

…と思っていたのだけれど、JDK1.4以降のjavadocでは問題ない。[2008-02-22]

フィールドのJavadocコメント

フィールドのJavadocコメントは、１つずつ指定してやらないとおかしくなる。

	/** サンプル */
	public int n1, n2, n3;

→n1・n2・n3の全てに同じ「サンプル」という説明が生成される。

	/** サンプル */
	public int n1;
	public int n2;
	public int n3;

→n1だけ「サンプル」という説明が生成され、n2・n3には説明が付かない。

HTMLのバグ

生成されるHTMLに、一部間違っている箇所がある。[2009-02-14]
（SunのJavadocのHTMLも間違っているので(苦笑)、Javadocツールのバグだろう）

クラス名のHTML

以下のようにクラス名が表示されるが、HTMLがおかしい。

public class HtParser
extends Object

<DL>
<DT><PRE>public class <B>HtParser</B><DT>extends <A HREF="〜">Object</A></DL>
</PRE>

DLのタグとPREのタグが入り繰りになっていて、片方しかマッチしない…。

使用メソッドのHTML

各クラスの説明の一番上のメニューのようなリンクから「使用」をクリックした場合、そのクラスを使用している箇所の一覧が表示される。
そこの「のメソッド」や「のサブクラス」のHTMLがおかしい。

<TH ALIGN="left" COLSPAN="2"><A HREF="〜/HtParser.html">HtParser</A> を返す
<A HREF="〜/package-summary.html">jp.hishidama.html.parser.rule</A> のメソッド</FONT>
</TH>

FONTの開始タグが無い。
ちなみに「メソッド」や「サブクラス」でなく「パッケージ」や「使用」といった行では<FONT SIZE="+2">があるのでそれにマッチしているのだが…。

定数フィールド値のHTML

Javadocのindex.htmlと同じディレクトリーに、constant-values.htmlという定数フィールド値の一覧のHTMLファイルが生成される。
この中でも開始タグの無い</font>や</td>・</tr>がある。