gihyo.jpサイトのロゴ

WEB+DB PRESS Vol.51 特集2「“巧い”メソッド設計」連動企画

第1回Javadocリファレンス

2009-06-29

はじめに

ここでは、WEB+DB PRESS Vol.51特集2「～現場の知恵と経験、絞り出しました～“⁠巧い⁠”メソッド設計」第7章「～ドキュメントツールJavadoc再入門～Javadocをコード品質の向上に活用しよう」と連動して、「⁠Javadocリファレンス」と題し、Javadocドキュメントにおけるコマンド、タグなどの書き方について解説します。

Javadocドキュメントに含まれるもの

Javadocドキュメントにはパッケージ、クラス、インタフェース、コンストラクタ、メソッド、フィールドなどの情報が含まれます。

Javadocでは、HTMLのタグを利用できます。JavadocツールはHTML 3.2に準拠したコードを生成しますが、フレームに対応するためHTML 4.01の文書として扱われます。どのタグが使えるのかを明記した公式の資料はありません。さまざまなブラウザで読まれることを考慮して使うタグを選択しなければなりません。表1に代表的なHTMLタグを示します。これ以外のタグを使う必要はないと思います。また、<H1>～<H6>、<HR>タグはJavadocの文書構造を壊す可能性があるので使用してはいけません。

表1　Javadocで使用するHTMLタグ
内容タグ
リンク・画像<A>、<IMG>
段落・改行<P>、<BR>
リスト<UL>、<OL>、<LI>
強調<B>、<I>
テーブル<TABLE>、<TR>、<TH>、<TD>

ドキュメントコメントの構造

ドキュメントコメントは主説明とタグセクションの2つで構成されます。主説明にはクラスやメソッドの責務や制約、使用例などを記述します。タグセクションには@で始まるドキュメントタグを記述し、パラメータや戻り値などの説明を行います（図1、図2⁠）⁠。

図1　ドキュメントコメントの記述例
図1　ドキュメントコメントの記述例
図2　ドキュメントコメントの出力例
図2　ドキュメントコメントの出力例

最初の文

主説明の最初の文は概要としてコピーされる簡潔な要約文です。パッケージの概要は、概要ページの概要テーブル、クラスの概要はパッケージページの概要テーブルにコピーされます。

最初の文は、次の条件で文が終了したと判定されます。

  • 。（⁠句点）が見つかった場合
  • 感嘆符や疑問符が見つかった場合
  • 後ろに空白、タグ、行末記号が続くピリオドが見つかった場合
  • 主説明の最後まで、区切りが見つからなかった場合

上記の区切り文字を最初の文で使う場合は、HTMLの数値文字参照を使ってエスケープします。

  • 例：ピリオド（.⁠）⁠ → &#x2E;

コメントの記述

Javadocで使用するドキュメントコメントファイルは表2のように4つに分けることができます。それぞれについてどういう内容を記述するのかを説明していきます。説明の例に標準ライブラリのクラス名やメソッド名を示しているものがいくつかあります。JDK（Java Development Kit）のJavadocは良質なコメントが多いので、実際にどのように記述しているかを参考にしてください。

表2　ドキュメントコメントファイル
ソースファイル内容ファイル名ディレクトリ
概要コメントファイルアプリケーションまたはパッケージセットに対してのコメントoverview.html（※）ソースディレクトリのルート
パッケージコメントファイルパッケージに対してのコメントpackage-info.javaパッケージディレクトリ
クラスソースファイルクラス、フィールド、メソッドに対してのコメント*.javaパッケージディレクトリ
その他（画像など)画像やDemoファイル、PDFファイルなど*.*パッケージディレクトリ/doc-files

※ javadocコマンドの-overviewオプションで指定するため、任意の名前で作成できます。

概要コメントファイル

アプリケーションまたはパッケージセットに対してのコメントファイルです（リスト1、図3⁠）⁠。概要コメントファイルはHTMLファイルとして作成します。公開ドキュメント用と内部向けドキュメント用の2つの概要コメントファイルを切り替えて使うことをお勧めします。

リスト1　概要コメントファイル（overview.html）
<!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>
    公開用の概要ファイルです。&lt;BODY&gt;タグの中身が概要コメントとして概要ファイルの最後にコピーされます。
    最初の文は概要ファイルの最初にもコピーされます。
    <P>
        概要コメントファイルには以下のような内容を記述します。
    <UL>
       <LI>アプリケーションまたはパッケージセットの全体に適用される内容
       <LI>使用している標準や規格などの説明、詳細情報へのリンク
       <LI>使用方法についての簡単な説明やサンプルコード
    </UL>
<!-- 内部向けであれば以下の内容も記述する
    <UL>
       <LI>アーキテクチャを採用した背景
       <LI>関連するシステムの情報。他システムとの連携の方法など。
    </UL>
-->
  </body>
</html>
図3　概要コメントファイルの出力例
図3　概要コメントファイルの出力例

パッケージコメントファイル

パッケージに対してのコメントファイルです（リスト2、図4⁠）⁠。パッケージの説明はパッケージページの最後にコピーされます。最初の文は概要ページの概要テーブルとパッケージページの先頭にコピーされます。

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

クラスソースファイル

クラスに対してのコメントを記述します（リスト3、図5⁠）⁠。最初の文はパッケージページの概要テーブルにコピーされます。メソッドの最初の文はクラスページのメソッド概要テーブルにコピーされます。

リスト3　クラス／メソッドのドキュメントコメント
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()
    {
    }
}
図5　クラスコメントの出力例
図5　クラスコメントの出力例

ここでメソッドコメントの具体例を2つ示します（リスト4、リスト5⁠）⁠。前者はメソッドの宣言以上のことを説明していないため、無意味なコメントになっています。このようなコメントを書いていては誰もJavadocを読む気にはなれません。

リスト4　悪い例
/**
 * 指定された名前と電話番号で登録します。
 * @param name 名前
 * @param tel 電話番号
 * @return 現在の人数
 */
public int entry(String name, String tel)
リスト5　良い例
/**
 * 指定された名前と連絡先で湯河原合宿の参加者として登録します。
 * 定員を超えた場合はキャンセル待ちとして扱います。
 * @param name 合宿参加者の名前を示す文字列
 * @param tel 連絡先の電話番号を示すハイフン区切りの文字列。
 *            電話番号にはnullを指定できます。
 * @return 受付を完了した参加者数。キャンセル待ちは含みません。
 * @see #getWaitingList() キャンセル待ちリスト
 */
public int entry(String name, String tel)

そのほかのファイル

Javadocドキュメントに画像ファイルを含めたいことがあると思います。その場合は、パッケージディレクトリ配下にdoc-filesというディレクトリを作成して、そこに画像ファイルを含めます。Javadocツールはdoc-filesディレクトリの内容を出力先ディレクトリにコピーします。

Javadocタグ

Javadocタグは、Javadocツールで処理するための特別なキーワードです。大文字と小文字が区別されます。ドキュメントタグはブロックタグとインラインタグの2つに分類されます。ブロックタグは @（アットマーク）で始まり、タグセクションの行頭で使用します。インラインタグは波括弧で囲まれ、説明文中で使用します。

なおJDKのバージョンは1.5以降を想定しています。

表3　ドキュメントタグ一覧
タグ内容複数回使用概要ファイルパッケージクラスメソッドフィールド
@param 型パラメータ 説明ジェネリクスの型パラメータと説明を記述します。○××○○×
@param 引数の名前 説明メソッドの引数の名前と説明を記述します。○×××○×
@return 説明メソッドの戻り値の説明を記述をします。××××○×
@throws クラス名 説明メソッドがスローする可能性のある例外について記述します。○×××○×
@author 作者名パッケージまたはクラスの作成者の名前を記述します。○○○○××
@version バージョン情報ソフトウェアのバージョンを記述します。○○○○××
@see package.class#member リンクの表示名クラス、メソッド、フィールドへのリンク情報を記述します。○○○○○○
@see <a href="URL">リンクの表示名相対URLまたは絶対URLへのリンクを記述します。○○○○○○
@see "参照先テキスト"URLでアクセスできない関連項目へのリンク情報を記述します。○○○○○○
@since 導入バージョンパッケージ、クラス、フィールド、メソッドが導入されたバージョンを記述します。○○○○○○
@serial フィールドの説明デフォルトの直列化可能なフィールドの意味、取り得る値のリストを示します。×××××○
@serial include | excludeパッケージを直列化された形式に表示するかどうかを指定します。××○○××
@serialField フィールド名 フィールドの型 説明serialPersistentFieldsフィールドによって宣言された直列化可能フィールドの説明を記述します。○××××○
@serialData 説明直列化された形式でのデータの型と順序を説明を記述します。××××○×
@deprecated 説明そのクラス、メソッド、フィールドの使用が非推奨になったことを示します。×××○○○
{@link package.class#member リンクの表示名}パッケージ、クラス、メンバーへのインラインリンクをコードとして表します。-○○○○○
{@linkplain package.class#member リンクの表示名}パッケージ、クラス、メンバーへのインラインリンクを表します。-○○○○○
{@docRoot}生成されるページから見た、生成ドキュメントのルートディレクトリへの相対パスを表します。-○○○○○
{@code コード}コードをスタイルで表示します。-○○○○○
{@literal テキスト}テキストをHTMLとして解釈せず、そのまま表示します。-○○○○○
{@inheritDoc}実装しているインタフェースまたは継承したスーパークラスのドキュメントコメントをコピーします。-×××○×
{@value package.class#field}定数フィールドの値を表示します。-○○○○○

ブロックタグについては慣習的に次の規約があります。

  • ブロックタグは表3ドキュメントタグ一覧の順番に記述する。
  • 同じタグは1ヵ所にグループ化して記述する。
  • 同じタグの中でも記述する順序がある。（⁠詳細は各タグの説明を参照）

以下、それぞれのタグについて一言解説していきます。

@param 型パラメータ説明

ジェネリックスの型パラメータを説明します。JDK 1.5以降で使用します。型パラメータの意味は明白であるため省略されることが多いです。

@param 引数の名前

生成ドキュメントの[パラメータ]の項目に表示されます。名前には宣言の引数名と同じ名前を記述します。パラメータの説明には引数の型や、事前条件、意味などを記述します。説明の最初の文は体言止めにします。事前条件には引数の値の範囲やnullを許可するかなどの条件を記述します。また引数に副作用がある場合は明記しておいたほうがよいでしょう。

@paramタグを複数使用する場合はメソッド宣言の引数と同じ順序で記述します。引数がない場合は@paramタグを記述しません。

@return 説明

生成ドキュメントの[戻り値]の項目に表示されます。戻り値の説明の最初の文は体言止めで記述します。次の文以降で戻り値の型や値の範囲などの事後条件について記述します。@returnタグはコンストラクタやvoidのメソッドでは使用しません。

@throws クラス名 説明

生成ドキュメントの[例外]の項目に表示されます[4]⁠。スローされる例外クラス名とその例外がどういう場合に発生するかを記述します。例外クラス名は単純名（パッケージを指定しないクラス名）で記述します。単純名で解決できない場合は「検索順序[5]⁠」に従ってクラスを検索します。例外の説明は体言止めで記述します。@throwsタグは複数指定できます。

チェックされる例外（try-catchまたはthrowsが必要な例外）はメソッド宣言に記述されているすべての例外について@throwsタグを記述します。実行時例外（RuntimeExceptionとそのサブクラス）は、事前条件に違反していることを示す例外を記述します。ただしメソッド内部の実装に依存した例外は記述してはいけません。記述すると公開APIの一部となってしまい、実装の変更ができなくなります。

  • 例）× ArrayIndexOutOfBoundsException
    •     ○ IndexOutOfBoundsException

前者は、内部のデータ構造が配列であることを公開してしまいますが、後者であれば別のデータ構造をとることができます。

Errorとそのサブクラスについては@throwsタグに記述してはいけません。

@author 作者名

生成ドキュメントの[作成者]の項目に表示されます。このタグはデフォルトでは無効になっているため、javadocコマンドで-authorオプションを指定して有効化する必要があります。パッケージの作成者はそのパッケージの仕様に対しての主な貢献者（個人またはグループ⁠）⁠、クラスの作成者はそのクラスの主な作成者を記述します。作成者を複数記述する場合は古いバージョンの作成者から順に記述します。

@version バージョン情報

生成ドキュメントの[バージョン]の項目に表示されます。このタグはデフォルトでは無効になっているため、javadocコマンドで-versionオプションを指定して有効化する必要があります。バージョンはCVSやSubversionのようなバージョン管理システムでファイルをチェックアウトしたときのバージョンを記述します。

/**
 * @version 1.51 2009/06/24
 */

@see package.class#member リンクの表示名

クラス、メソッド、フィールドへのリンク情報を記述します。

同一クラス内へのリンクの場合、パッケージ名とクラス名を省略できます。同一パッケージのクラスへのリンクの場合、パッケージ名を省略できます。リンクの表示名を省略した場合はpackage.class#memberが使われます。

ドキュメント化の対象ではないクラスにリンクする場合はjavadocコマンドの-linkオプションを指定します。

オーバーロードされたメソッドへのリンクを指定する場合にはメソッドの()を省略します。特定のメソッドだけにリンクしたい場合は引数の型を指定します。

複数指定する場合の記述の順序は慣習的に以下のようにします。

  1. 同一クラス内への参照
  2. 同一パッケージ内のクラスへの参照
  3. ほかのパッケージのクラスへの参照

同じクラス内での記述の順序は次のとおりにします。

  1. フィールド
  2. コンストラクタ
  3. メソッド
  4. ネストしたクラス

フィールドやメソッドが複数ある場合はアルファベット順かほかの論理的なまとまりで順序づけします。

コンストラクタやオーバーロードされたメソッドは引数の数の少ないものから順番に、引数が同数の場合はアルファベット順やほかの論理的な順序で記述します。

@see <a href="URL">リンクの表示名</a>

相対URLまたは絶対URLへのリンクを記述します。直接リンク先を指定できるため、作成するドキュメントに含まれるPDFやサンプルコードなどへのリンク、情報源となる外部サイトを指定します。

@see "参照先テキスト"

この形式では"参照先テキスト"はリンクとしては生成されません。タグへの引数には書籍や設計書の名前などURLではアクセスできない情報を指定します。参照の文字列は二重引用符で囲む必要があります。

@since 導入バージョン

生成ドキュメントの[導入されたバージョン]の項目に表示されます。ここでのバージョンはバージョン管理システムのバージョンではなく、ソフトウェアのリリースバージョンを記述します。複数のソフトウェアで使用されている場合にはそれぞれのバージョンを指定します。

@serial フィールドの説明

生成ドキュメントの[直列化された形式]-[直列化されたフィールド]の項目に表示されます（注6、注7⁠）⁠。最初のリリース後にフィールドを追加した場合は追加したバージョンを@sinceタグを使って示します。

@serial include

package privateクラスやprivateクラスを[直列化された形式]のページに表示することを示します。ただしパッケージがexclude指定されている場合は表示されません。

@serial exclude

publicクラスやprotectedクラスを[直列化された形式]のページに表示しないことを示します。パッケージでexclude指定するとパッケージのすべてのクラスが表示されません。

@serialField フィールド名 フィールドの型 説明

生成ドキュメントの[直列化された形式]-[直列化されたフィールド]の項目に表示されます。ObjectStreamField配列の各要素の対して@serialFieldタグを記述する必要があります（リスト6[8]⁠）⁠。

リスト6　@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メソッド、readObjectメソッド、writeExternalメソッド、readExternalメソッド、writeReplaceメソッド、およびreadResolveメソッドで使用します[9]⁠。

@deprecated 説明

最初の文に非推奨になった時期と代替手段のリンク先（{@link}を使う）を記述します。その後の文で非推奨になった理由を説明します。最初の文は概要セクションと索引にコピーされます。

JDK 5.0以降で作成する場合は@Deprecatedアノテーションと@deprecatedタグの両方を使います（リスト7⁠）⁠。@deprecatedタグは単なるドキュメンテーションであり、プログラムとしての影響力はありません（javacで警告が出ますが、言語仕様上は意味をなしません⁠）⁠。一方、@Deprecatedアノテーションはコンパイル時も実行時にも非推奨として認識できますが、代替手段を示すことができません。

リスト7　@deprecated
/**
 * @deprecated 1.2以降では{@link hoge()}を使用してください。indexはまったく使っていないため、引数なしのメソッドに移行してください。
 */
 @Deprecated
 public void hoge(int index)

{@link package.class#member リンクの表示名}

パッケージ、クラス、メンバーへのインラインリンクを表します。{@link}タグは@seeタグと同じようにリンクを作成しますが、[関連項目]ではなく、説明文中にインラインで作成されます。また{@link}タグは何度でも、どこでも使用できます。リンクの表示名を省略した場合はpackage.class#memberが使われます。ドキュメント化の対象ではないクラスにリンクする場合はjavadocコマンドの-linkオプションを指定します。

{@linkplain package.class#member リンクの表示名}

パッケージ、クラス、メンバーへのインラインリンクを表します。{@link}タグとの違いはリンクの表示名を<code>スタイルではなく通常のテキストで表示することです。

{@docRoot}

生成されるページから見た、生成ドキュメントのルートディレクトリへの相対パスを表します。このタグは著作権表示や会社のロゴなどすべてのページから参照されるファイルを組み込むときに使います。ドキュメントコメント本文中でも使えますが、ヘッダやフッタの定義に使うとより効果的です。

{@code コード}

コードを<code>スタイルで表示します。このタグはJDK 1.5から導入されました。{@code}タグは<code>{@literal}</code>と同等です。{@code}タグを使うと不等号記号をそのまま使えます。

例）{@code index > 0} ⇒ <code>index &gt; 0</code>

{@code}は次のものを記述するときに使います。

  • Java言語のキーワード
  • パッケージ名
  • クラス名
  • メソッド名
  • インタフェース名
  • フィールド名
  • 引数名
  • コードのサンプル

{@literal テキスト}

テキストをHTMLとして解釈せず、そのまま表示します。このタグはJDK 1.5から導入されました。{@literal}タグを使うと不等号記号をそのまま使えます。

{@inheritDoc}

実装しているインタフェースまたは継承したスーパークラスのドキュメントコメントをコピーします。メソッドの主説明、@returnタグ、@paramタグ、@throwsタグで利用できます。インタフェースとスーパークラスの両方にドキュメントコメントが記述されている場合はインタフェースのコメントが優先されて継承されます。継承するドキュメントはドキュメント化対象のクラスまたはjavadocコマンドの-sourcepathで指定したパスのクラスである必要があります。

{@inheritDoc}タグを使う上で注意点が3つあります。

1つめはコピーされるのはJavadocドキュメントからではなく、ソースコードのドキュメントコメントからであるということです。たとえば、JDKのObject#toString()のコメントを{@inheritDoc}でコピーする場合、JDK付属のソースから英語のコメントがコピーされます。

2つめはインタフェースまたはスーパークラスのメソッドのドキュメントコメントがそのままコピーされるということです。そのため、リスト8、リスト9のように継承元と矛盾を生じることがあります[10]⁠。

リスト8　スーパークラスのコメント
/**
 * @return 値が設定されていない場合、このメソッドはnullを返します。
 */
リスト9　サブクラスのコメント
/**
 * @return {@inheritDoc}
 * このメソッドはnullを返すことはありません。
 */

3つめは例外はthrowsに宣言されているものだけが継承されることです（リスト10⁠）⁠。実行時例外は自動的には継承されないため、必要であればその例外の@throwsタグの説明だけを継承するようにします。ここでも継承元と矛盾しないように注意してください。

リスト10　@throwsタグ
/**
 * @throws IllegalArgumentException {@inheritDoc}
 */

{@value package.class#field}

生成ドキュメントの[フィールドの詳細]に定数の説明の一部として定数値が表示されます。定数フィールドのドキュメントコメントで{@value}の引数を省略した場合は、そのフィールドの値を表示します。

引数を指定した場合は定数フィールド以外の場所でも利用でき、その定数フィールドの値を表示します。

おすすめ記事

記事・ニュース一覧