はじめに
ここでは、
Javadocドキュメントに含まれるもの
Javadocドキュメントにはパッケージ、
Javadocでは、
内容 | タグ |
---|---|
リンク・ | <A>、 |
段落・ | <P>、 |
リスト | <UL>、 |
強調 | <B>、 |
テーブル | <TABLE>、 |
ドキュメントコメントの構造
ドキュメントコメントは主説明とタグセクションの2つで構成されます。主説明にはクラスやメソッドの責務や制約、


最初の文
主説明の最初の文は概要としてコピーされる簡潔な要約文です。パッケージの概要は、
最初の文は、
- 。(句点)
が見つかった場合 - 感嘆符や疑問符が見つかった場合
- 後ろに空白、
タグ、 行末記号が続くピリオドが見つかった場合 - 主説明の最後まで、
区切りが見つからなかった場合
上記の区切り文字を最初の文で使う場合は、
- 例:ピリオド
(.) → .
コメントの記述
Javadocで使用するドキュメントコメントファイルは表2のように4つに分けることができます。それぞれについてどういう内容を記述するのかを説明していきます。説明の例に標準ライブラリのクラス名やメソッド名を示しているものがいくつかあります。JDK
ソースファイル | 内容 | ファイル名 | ディレクトリ |
---|---|---|---|
概要コメントファイル | アプリケーションまたはパッケージセットに対してのコメント | overview. | ソースディレクトリのルート |
パッケージコメントファイル | パッケージに対してのコメント | package-info. | パッケージディレクトリ |
クラスソースファイル | クラス、 | *.java | パッケージディレクトリ |
その他 | 画像やDemoファイル、 | *.* | パッケージディレクトリ/doc-files |
※ javadocコマンドの-overviewオプションで指定するため、
概要コメントファイル
アプリケーションまたはパッケージセットに対してのコメントファイルです
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=Shift_JIS">
</head>
<body>
公開用の概要ファイルです。<BODY>タグの中身が概要コメントとして概要ファイルの最後にコピーされます。
最初の文は概要ファイルの最初にもコピーされます。
<P>
概要コメントファイルには以下のような内容を記述します。
<UL>
<LI>アプリケーションまたはパッケージセットの全体に適用される内容
<LI>使用している標準や規格などの説明、詳細情報へのリンク
<LI>使用方法についての簡単な説明やサンプルコード
</UL>
<!-- 内部向けであれば以下の内容も記述する
<UL>
<LI>アーキテクチャを採用した背景
<LI>関連するシステムの情報。他システムとの連携の方法など。
</UL>
-->
</body>
</html>

パッケージコメントファイル
パッケージに対してのコメントファイルです
/**
* webdb51パッケージの説明を記述します。
* <P>
* パッケージコメントファイルには以下の内容を記述します。
* <UL>
* <LI>パッケージが提供する機能についての説明
* <LI>パッケージを使用するときにキーとなるオブジェクトの説明
* <LI>パッケージ内のクラスの分類や重要な用語の説明。例)java.netパッケージ
* <LI>OSやハードウェアへの依存性
* <LI>外部仕様への参照。例)java.utilパッケージ
* </UL>
*/
package webdb51;

クラスソースファイル
クラスに対してのコメントを記述します
package webdb51;
import java.io.IOException;
import java.io.Serializable;
import java.util.List;
/**
* クラスに対してのコメントを記述します。
* ここでは以下の内容を記述します。
* <UL>
* <LI>クラスがどういうことをするのかの説明
* <LI>インスタンスが取り得る状態についての情報。
* 例) ファイルがオープンされている状態とクローズされた状態での振る舞い。
* <LI>OSやハードウェアへの依存性。例)java.io.Fileクラス
* <LI>クラスの不変条件や一般契約。例)java.lang.Comparableインタフェース
* <LI>インスタンスのスレッド安全性レベル[2]。
* 例)java.lang.Appendableインタフェース
* <LI>セキュリティ制約。例)java.lang.RuntimePermissionクラス
* <LI>直列化の形式
* <LI>インタフェースを実装する場合またはクラスを継承する場合の注意点。
* 例)java.util.AbstractListクラス
* <LI>他のクラスとの関連性。
* <LI>外部仕様への参照。例)java.net.URLクラス
* @see "Effective Java第2版"
*/
public class DocSample implements Serializable
{
/**
* フィールドの説明。
* @serial 直列化されるフィールドの説明。
* 以下の内容を記述します。
* <UL>
* <LI>フィールドが表しているもの
* <LI>有効な値の範囲。例)java.awt.Font#style
* <LI>nullを許可するか
* </UL>
*/
private String field1;
/**
* 定数が意味することを説明する。例)java.lang.Integer#MAX_VALUE
*/
public static final int CONST1 = 0;
/**
* publicメソッドにはAPI利用者向けに以下の説明を記述します。
* <UL>
* <LI>メソッドの期待される振る舞い
* <LI>状態がどのように遷移するか。
* 例)close()メソッドによってオブジェクトがclose状態に遷移する。
* <LI>メソッドの副作用の有無とその内容。副作用とは事後条件を達成するのに
* 明らかに必要としない変化[3]。
* 例) バックグラウンドのスレッドを起動する。
* <LI>メソッド呼び出しの事前条件、事後条件。例)Integer.parseInt(String)
* <LI>スレッド安全性レベル
* <LI>セキュリティ制約
* <LI>使用するアルゴリズムの定義。例)java.lang.String#hashCode()メソッド
* (どのように実装しているかではありません。)
* <LI>OSやハードウェアへの依存性。例)java.io.File#getCanonicalPathメソッド
* </UL>
* @param param1 パラメータの説明。有効な引数の範囲やnullを許容するかを記述します。
* @param list パラメータに副作用がある場合はその内容を明記する。
* @return 戻り値の説明。戻り値の値の範囲や型、nullの可能性を記述する。
* @throws IOException 例外の説明。例外の発生原因を記述する。
* チェックされる例外はすべて書く。
* @throws NullPointerException 実行時例外は必要なものだけ記述する。
*/
public int function1(int param1, List list) throws IOException
{
list.add(param1);
return list.size();
}
/**
* protectedメソッドは継承利用者向けにメソッドの内容を説明します。
* publicメソッドに記述する内容に加えて以下の内容を記述します。
* <UL>
* <LI>オーバーライドするときの注意点。
* 例)javax.servlet.GenericServlet#init(ServletConfig)メソッド
* <LI>守るべき不変条件や一般契約。
* 例)java.lang.Object#equals(Object)メソッド
* </UL>
* @throws IOException チェックされる例外のコメントはサブクラスに自動的に継承されます。
* @throws IllegalStateException 実行時例外のコメントは手動で継承しなければなりません。
*/
protected void function2() throws IOException
{
}
/**
* package privateメソッド、privateメソッドは保守担当者向けに以下の内容を記述します。
* <UL>
* <LI>実装のアルゴリズム。外部には見せないので、どのように実装しているかまで記述してもよいです。
* <LI>データ構造
* <LI>なぜそのような実装にしたのか。採用するときに参考にした参考資料等を記述する。
* 例)J2EEパターンのFrontControllerパターンを元に作成した。
* <LI>未解決の問題点。開発期間や技術上の未解決の問題について記述する。
* 例)JDK 1.5以降で開発する場合は、Class#getSimpleName()でクラス名を取得する。
* <LI>改善ポイントや代替手段
* </UL>
*/
private void function3()
{
}
}

ここでメソッドコメントの具体例を2つ示します
/**
* 指定された名前と電話番号で登録します。
* @param name 名前
* @param tel 電話番号
* @return 現在の人数
*/
public int entry(String name, String tel)
/**
* 指定された名前と連絡先で湯河原合宿の参加者として登録します。
* 定員を超えた場合はキャンセル待ちとして扱います。
* @param name 合宿参加者の名前を示す文字列
* @param tel 連絡先の電話番号を示すハイフン区切りの文字列。
* 電話番号にはnullを指定できます。
* @return 受付を完了した参加者数。キャンセル待ちは含みません。
* @see #getWaitingList() キャンセル待ちリスト
*/
public int entry(String name, String tel)
そのほかのファイル
Javadocドキュメントに画像ファイルを含めたいことがあると思います。その場合は、
Javadocタグ
Javadocタグは、
なおJDKのバージョンは1.
タグ | 内容 | 複数回使用 | 概要ファイル | パッケージ | クラス | メソッド | フィールド |
---|---|---|---|---|---|---|---|
@param 型パラメータ 説明 | ジェネリクスの型パラメータと説明を記述します。 | ○ | × | × | ○ | ○ | × |
@param 引数の名前 説明 | メソッドの引数の名前と説明を記述します。 | ○ | × | × | × | ○ | × |
@return 説明 | メソッドの戻り値の説明を記述をします。 | × | × | × | × | ○ | × |
@throws クラス名 説明 | メソッドがスローする可能性のある例外について記述します。 | ○ | × | × | × | ○ | × |
@author 作者名 | パッケージまたはクラスの作成者の名前を記述します。 | ○ | ○ | ○ | ○ | × | × |
@version バージョン情報 | ソフトウェアのバージョンを記述します。 | ○ | ○ | ○ | ○ | × | × |
@see package. | クラス、メソッド、フィールドへのリンク情報を記述します。 | ○ | ○ | ○ | ○ | ○ | ○ |
@see <a href="URL">リンクの表示名 | 相対URLまたは絶対URLへのリンクを記述します。 | ○ | ○ | ○ | ○ | ○ | ○ |
@see "参照先テキスト" | URLでアクセスできない関連項目へのリンク情報を記述します。 | ○ | ○ | ○ | ○ | ○ | ○ |
@since 導入バージョン | パッケージ、クラス、フィールド、メソッドが導入されたバージョンを記述します。 | ○ | ○ | ○ | ○ | ○ | ○ |
@serial フィールドの説明 | デフォルトの直列化可能なフィールドの意味、取り得る値のリストを示します。 | × | × | × | × | × | ○ |
@serial include | exclude | パッケージを直列化された形式に表示するかどうかを指定します。 | × | × | ○ | ○ | × | × |
@serialField フィールド名 フィールドの型 説明 | serialPersistentFieldsフィールドによって宣言された直列化可能フィールドの説明を記述します。 | ○ | × | × | × | × | ○ |
@serialData 説明 | 直列化された形式でのデータの型と順序を説明を記述します。 | × | × | × | × | ○ | × |
@deprecated 説明 | そのクラス、メソッド、フィールドの使用が非推奨になったことを示します。 | × | × | × | ○ | ○ | ○ |
{@link package. | パッケージ、クラス、メンバーへのインラインリンクをコードとして表します。 | - | ○ | ○ | ○ | ○ | ○ |
{@linkplain package. | パッケージ、クラス、メンバーへのインラインリンクを表します。 | - | ○ | ○ | ○ | ○ | ○ |
{@docRoot} | 生成されるページから見た、生成ドキュメントのルートディレクトリへの相対パスを表します。 | - | ○ | ○ | ○ | ○ | ○ |
{@code コード} | コードをスタイルで表示します。 | - | ○ | ○ | ○ | ○ | ○ |
{@literal テキスト} | テキストをHTMLとして解釈せず、そのまま表示します。 | - | ○ | ○ | ○ | ○ | ○ |
{@inheritDoc} | 実装しているインタフェースまたは継承したスーパークラスのドキュメントコメントをコピーします。 | - | × | × | × | ○ | × |
{@value package. | 定数フィールドの値を表示します。 | - | ○ | ○ | ○ | ○ | ○ |
ブロックタグについては慣習的に次の規約があります。
- ブロックタグは表3ドキュメントタグ一覧の順番に記述する。
- 同じタグは1ヵ所にグループ化して記述する。
- 同じタグの中でも記述する順序がある。
(詳細は各タグの説明を参照)
以下、
@param 型パラメータ説明
ジェネリックスの型パラメータを説明します。JDK 1.
@param 引数の名前
生成ドキュメントの[パラメータ]の項目に表示されます。名前には宣言の引数名と同じ名前を記述します。パラメータの説明には引数の型や、
@paramタグを複数使用する場合はメソッド宣言の引数と同じ順序で記述します。引数がない場合は@paramタグを記述しません。
@return 説明
生成ドキュメントの[戻り値]の項目に表示されます。戻り値の説明の最初の文は体言止めで記述します。次の文以降で戻り値の型や値の範囲などの事後条件について記述します。@returnタグはコンストラクタやvoidのメソッドでは使用しません。
@throws クラス名 説明
生成ドキュメントの[例外]の項目に表示されます
チェックされる例外
- 例)× ArrayIndexOutOfBoundsException ○ IndexOutOfBoundsException
前者は、
Errorとそのサブクラスについては@throwsタグに記述してはいけません。
@author 作者名
生成ドキュメントの[作成者]の項目に表示されます。このタグはデフォルトでは無効になっているため、
@version バージョン情報
生成ドキュメントの[バージョン]の項目に表示されます。このタグはデフォルトでは無効になっているため、
/**
* @version 1.51 2009/06/24
*/
@see package.class#member リンクの表示名
クラス、
同一クラス内へのリンクの場合、
ドキュメント化の対象ではないクラスにリンクする場合はjavadocコマンドの-linkオプションを指定します。
オーバーロードされたメソッドへのリンクを指定する場合にはメソッドの()を省略します。特定のメソッドだけにリンクしたい場合は引数の型を指定します。
複数指定する場合の記述の順序は慣習的に以下のようにします。
- 同一クラス内への参照
- 同一パッケージ内のクラスへの参照
- ほかのパッケージのクラスへの参照
同じクラス内での記述の順序は次のとおりにします。
- フィールド
- コンストラクタ
- メソッド
- ネストしたクラス
フィールドやメソッドが複数ある場合はアルファベット順かほかの論理的なまとまりで順序づけします。
コンストラクタやオーバーロードされたメソッドは引数の数の少ないものから順番に、
@see <a href="URL">リンクの表示名</a>
相対URLまたは絶対URLへのリンクを記述します。直接リンク先を指定できるため、
@see "参照先テキスト"
この形式では"参照先テキスト"はリンクとしては生成されません。タグへの引数には書籍や設計書の名前などURLではアクセスできない情報を指定します。参照の文字列は二重引用符で囲む必要があります。
@since 導入バージョン
生成ドキュメントの[導入されたバージョン]の項目に表示されます。ここでのバージョンはバージョン管理システムのバージョンではなく、
@serial フィールドの説明
生成ドキュメントの[直列化された形式]-[直列化されたフィールド]の項目に表示されます
@serial include
package privateクラスやprivateクラスを[直列化された形式]のページに表示することを示します。ただしパッケージがexclude指定されている場合は表示されません。
@serial exclude
publicクラスやprotectedクラスを[直列化された形式]のページに表示しないことを示します。パッケージでexclude指定するとパッケージのすべてのクラスが表示されません。
@serialField フィールド名 フィールドの型 説明
生成ドキュメントの[直列化された形式]-[直列化されたフィールド]の項目に表示されます。ObjectStreamField配列の各要素の対して@serialFieldタグを記述する必要があります
/**
* @serialField id int会員のID番号。正の値だけ取り得ます。
* @serialField name String会員の名前。この値はnullになることがあります。
*/
private static final ObjectStreamField[] serialPersistentFields = {
new ObjectStreamField("id", int.class),
new ObjectStreamField("name", String.class)
};
@serialData 説明
生成ドキュメントの[直列化された形式]-[直列化メソッド]-[シリアルデータ]の項目に表示されます。このタグはwriteObjectメソッド、
@deprecated 説明
最初の文に非推奨になった時期と代替手段のリンク先
JDK 5.
/**
* @deprecated 1.2以降では{@link hoge()}を使用してください。indexはまったく使っていないため、引数なしのメソッドに移行してください。
*/
@Deprecated
public void hoge(int index)
{@link package.class#member リンクの表示名}
パッケージ、
{@linkplain package.class#member リンクの表示名}
パッケージ、
{@docRoot}
生成されるページから見た、
{@code コード}
コードを<code>スタイルで表示します。このタグはJDK 1.
{@code}は次のものを記述するときに使います。
- Java言語のキーワード
- パッケージ名
- クラス名
- メソッド名
- インタフェース名
- フィールド名
- 引数名
- コードのサンプル
{@literal テキスト}
テキストをHTMLとして解釈せず、
{@inheritDoc}
実装しているインタフェースまたは継承したスーパークラスのドキュメントコメントをコピーします。メソッドの主説明、
{@inheritDoc}タグを使う上で注意点が3つあります。
1つめはコピーされるのはJavadocドキュメントからではなく、
2つめはインタフェースまたはスーパークラスのメソッドのドキュメントコメントがそのままコピーされるということです。そのため、
/**
* @return 値が設定されていない場合、このメソッドはnullを返します。
*/
/**
* @return {@inheritDoc}
* このメソッドはnullを返すことはありません。
*/
3つめは例外はthrowsに宣言されているものだけが継承されることです
/**
* @throws IllegalArgumentException {@inheritDoc}
*/
{@value package.class#field}
生成ドキュメントの[フィールドの詳細]に定数の説明の一部として定数値が表示されます。定数フィールドのドキュメントコメントで{@value}の引数を省略した場合は、
引数を指定した場合は定数フィールド以外の場所でも利用でき、