Javadocタグ

@authorタグ

@authorタグはクラス、インターフェイスなどに書き、作成者を指定するために使用する。

@author name-text

著者に関する情報を指定する。

記述位置 : 概要、パッケージ、クラス、インターフェイス
複数記述 : 可能
出力形式 : 作成者
その他 : "-author"オプションが必要

主にクラスなどのコメントを書き、著者が誰なのかを指定する場合に使用する。同じコメント内で複数回指定できる。

/**
 * コメントの説明文
 * @author devkuma
 * @author kimkc
 */

@authorタグが複数書かれた場合、出力時にはそれぞれの著者がカンマで区切られ、1行にまとめて出力される。

なお、Javadocの-authorオプションを指定した場合にだけ出力される。-authorオプションについては、-authorオプションページを参照してほしい。

@authorタグの実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 * @author devkuma
 * @author kimkc
 */
public class Sample05 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     */
    public void setSize(int width, int height) {

    }
}

上のソースコードをSample05.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc -author Sample05.java

生成されたdocディレクトリにあるSample05.htmlファイルをブラウザで確認してみよう。

クラスの説明部分に、@authorに書いた名前が「作成者(author)」として表示されている。@authorタグを複数指定したため、1行にまとめて表示されていることを確認できる。

@versionタグ

@versionタグはクラス、インターフェイスなどに書き、ソフトウェアのバージョンを指定するために使用する。

@version version-text

ソフトウェアのバージョンを指定する。

記述位置 : 概要、パッケージ、クラス、インターフェイス
複数記述 : 可能
出力形式 : バージョン
その他 : "-version"オプションが必要

ソフトウェアの現在のバージョンを指定する場合に使用する。同じコメント内で複数回指定できる。

/**
 * コメントの説明文
 * 
 * @version 1.0
 * @version Project 2.0.1
 */

@versionタグが複数書かれた場合、出力時にはそれぞれのバージョンがカンマで区切られ、1行にまとめて出力される。

似たタグに@sinceがあるが、このタグは現在のバージョンではなく、導入されたバージョンを指定する場合に使用する。

注意点として、Javadocの-versionオプションを指定した場合にだけ出力される。-versionオプションについては、-versionオプションページを参照してほしい。

@versionタグのサンプル

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 *
 * @version 1.0
 * @version Project 2.0.1
 */
public class Sample06 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     */
    public void setSize(int width, int height) {

    }
}

上のソースコードをSample06.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc -version Sample06.java

生成されたdocディレクトリにあるSample06.htmlファイルをブラウザで確認してみよう。

クラスの説明部分に、@versionに書いたバージョンが「バージョン(version)」として表示されている。@versionタグを複数指定したため、1行にまとめて表示されていることを確認できる。

@seeタグ

@seeタグは、関連項目として外部リンクやテキストを表示したり、他のフィールドやメソッドへの参照リンクを示したりする場合に使用する。

@see reference

関連項目としてテキストとリンクを表示する。

記述位置 : 概要、パッケージ、クラス、インターフェイス、フィールド、メソッド
複数記述 : 可能
出力形式 : 関連項目

テキスト、外部リンク

@seeタグは、テキストや外部リンクとして使用できる。その使い方を見てみよう。

まず、関連項目の位置情報を文字列として表示する場合である。

@see "string"

表示する文字列をダブルクォーテーションで囲んで指定する。使い方は次のとおりである。

/**
 * コメントの説明文
 * @see "Java"
 */
 ```

次は、外部サイトへのリンクを表示する場合である。

```java
@see <a href="URL">label</a>

HTML文の<a>タグと同じ形式でリンクとラベルを指定する。使い方は次のとおりである。

/**
 * コメントの説明文
 * @see <a href="http://www.devkuma.com">デブクマ</a>
 */

@seeタグが複数書かれた場合、出力時にはそれぞれのリンクラベルがカンマで区切られ、1行にまとめて出力される。

@seeタグの実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 *
 * @see "Java"
 * @see <a href="http://www.devkuma.com">デブクマ</a>
 */
public class Sample07 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     * @see <a href="https://www.google.com/">Google</a>
     */
    public void setSize(int width, int height) {

    }
}

上のソースコードをSample07.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

クラスとメソッドに@seeタグを使用して関連情報が表示されている。@seeタグを複数指定したため、1行にまとめて表示されていることを確認できる。

参照リンク

@seeタグのもう1つの使い方として、他のフィールドやメソッドへの参照リンクを表示するために使用する。

他のフィールドやメソッドへの参照リンクを表示する場合である。

@see package.class#member label

package.class#member形式で指定した他のメソッドへのリンクを作成する。リンクラベルとしてlabelを表示するが、labelは任意である。省略した場合は対象メソッド名で表示される。

/**
 * コメントの説明文
 * @see Sample08_02#setSize(int, int) setSize
 */

上ではパッケージ名を省略している。このようにパッケージ名を省略したり、クラス名まで省略して書いたりした場合は、省略された部分を次の順序で検索する。

1. 現在のクラスまたはインターフェイス
2. 外側を囲んでいるクラスとインターフェイス。もっとも近いものから検索する
3. スーパークラスとスーパーインターフェイス。もっとも近いものから検索する
4. 現在のパッケージ
5. importされたパッケージ、クラス、インターフェイス。import文の順序に従って検索する

常に完全名でパッケージからメンバーまでを指定すれば確実だが、コメントが長くなりすぎることがある。省略すると、コメント部分を簡潔に書ける。

公式資料によると、次のような書き方がある。

現在のクラスのメンバーを参照する。

@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)

現在またはimportされたパッケージの別のクラスを参照する。

@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class

別のパッケージの要素を参照する。これは完全に明示的な指定である。

@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package

実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 *
 * @see Sample08_02
 */
public class Sample08_01 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     * @see Sample08_02#getWidth()
     * @see Sample08_02#getHeight()
     */
    public void setSize(int width, int height) {

    }
}

/**
 * Javadocテスト用クラス
 *
 * @see Sample08_01
 */
public class Sample08_02 {

    /**
     * 幅を返す
     *
     * @return 幅
     * @see Sample08_01#setSize(int, int)
     * @see #getHeight()
     */
    public int getWidth() {
        return 0;
    }

    /**
     * 高さを返す
     *
     * @return 高さ
     * @see Sample08_01#setSize(int, int)
     * @see #getWidth()
     */
    public int getHeight() {
        return 0;
    }
}

上のソースコードをSample08_01.javaとSample08_02.javaというファイル名でそれぞれ保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample08_01.java Sample08_02.java

生成されたdocディレクトリにあるSample08_01.htmlファイルをブラウザで確認してみよう。

Sample08_01クラスについては、コメントでSample08_02クラスへのリンクが設定されているため、「関連項目」にはSample08_02クラスへの参照リンクが表示されている。

そしてsetSizeメソッドには、Sample08_02クラスのgetWidthメソッドとgetHeightメソッドへのリンクが設定されている。ここでもメソッドの「関連項目」には、それぞれのメソッドへの参照リンクが表示されている。

@deprecatedタグ

@deprecatedタグは、クラスやメソッドなどの使用が今後推奨されない場合に使用する。使用が推奨されないということは、使用できないという意味ではない。ただし推奨されず、将来なくなる可能性があるという意味である。

@deprecated deprecated-text

使用を推奨しない場合に指定する。

記述位置 : 概要、パッケージ、クラス、インターフェイス、フィールド、メソッド
複数記述 : 不可
出力形式 : Deprecated. + 入力した文字列

使用を推奨しなくなった理由などを文字列で書く。使い方は次のとおりである。

/**
 * コメントの説明文
 * @deprecated 別の方法で置き換えられた。
 */

また、代替となるメソッドやクラスなどへのリンクを続けて指定する。リンクの指定には{@link}タグを使用する。

/**
 * コメントの説明文
 * @deprecated 別のメソッドで置き換えられた {@link #setScale()}
 */

@deprecatedに指定した文字列は、Deprecated.という文字列とともにコメントの説明文の前に表示される。

@deprecatedタグの実習

それでは簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 */
public class Sample09 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     * @see Sample08_02#getWidth()
     * @see Sample08_02#getHeight()
     * @deprecated 別のメソッドで置き換えられた {@link #setScale(int, int)}
     */
    public void setSize(int width, int height) {

    }

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     */
    public void setScale(int width, int height){

    }
}

上のソースコードをSample09.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample09.java

生成されたdocディレクトリにあるSample09.htmlファイルをブラウザで確認してみよう。

メソッドにDeprecated.が先に表示され、その後に@deprecatedタグで書いた内容が表示されていることが分かる。

@deprecatedタグで書いた内容は、コメントの説明文より前に表示される点に注意しよう。

現在では、非推奨のメソッドやクラスの前に、コードとして@Deprecatedアノテーションを付けることが推奨されている。

@sinceタグ

@sinceタグは、導入されたバージョンを表示する場合に使用する。@versionタグが現在のバージョンを表すのに対し、@sinceタグはどのバージョンで導入されたかを表す点が異なる。

@since since-text

導入されたバージョンを表示する。

記述位置 : 概要、パッケージ、クラス、インターフェイス、フィールド、メソッド
複数記述 : 可能
出力形式 : 導入されたバージョン

バージョンなどを表す文字列を指定する。使い方は次のとおりである。

/**
 * コメントの説明文
 * @since 2.5.1
 */

@sinceタグが複数書かれた場合、出力時にはそれぞれのバージョンがカンマで区切られ、1行にまとめて出力される。

@sinceタグの実習

それでは簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 *
 * @since 2.5.1
 * @since Project 1.4A
 */
public class Sample10 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     * @since 1.8
     */
    public void setSize(int width, int height) {

    }
}

上のソースコードをSample10.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample10.java

生成されたdocディレクトリにあるSample10.htmlファイルをブラウザで確認してみよう。

@sinceタグを複数指定したため、1行にまとめて表示されていることを確認できる。

@paramタグ

@paramタグは、パラメータに関する説明を表示するときに使用する。

@param parameter-name description

パラメータに関する説明を表示する。

記述位置 : メソッド
複数記述 : 可能
出力形式 : パラメータ名および説明

@paramタグが複数書かれた場合、出力時にはそれぞれのパラメータが別の行に表示される。

メソッドのパラメータ名と、そのパラメータに関する説明を書く。使い方は次のとおりである。

/**
 * コメントの説明文
 * @param width 幅
 * @param height 高さ
 */
 ```
説明部分は複数行にわたって書ける。複数行にまたがることを表すための特別な書き方があるわけではない。

```java
/**
 * コメントの説明文
 * @param width 幅
 * widthに関する説明の2行目
 * widthに関する説明の3行目
 * @param height 高さ
 */

@paramタグの実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 */
public class Sample11 {

    /**
     * サイズを設定する
     *
     * @param width 幅<br>
     * 単位はセンチメートル
     * @param height 高さ
     */
    public void setSize(int width, int height) {

    }
}

上のソースコードをSample11.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample11.java

生成されたdocディレクトリにあるSample11.htmlファイルをブラウザで確認してみよう。

複数行で説明を書いた場合も、HTML文書として扱われることに注意しよう。改行する場合は、<br>などの改行用タグが必要である。

@returnタグ

@returnタグは、戻り値に関する説明、たとえばデータ型や範囲などを表示するときに使用する。

@return description

戻り値に関する説明を表示する。

記述位置 : メソッド
複数記述 : 不可
出力形式 : 戻り値

メソッドの戻り値に関する説明を書く。使い方は次のとおりである。

/**
 * コメントの説明文
 * @return 計算した面積
 */

@returnタグの実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 */
public class Sample12 {

    /**
     * サイズを設定する
     *
     * @param width 幅
     * @param height 高さ
     * @return 計算した面積
     */
    public int getSize(int width, int height) {
        return width * height;
    }
}

上のソースコードをSample12.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample12.java

生成されたdocディレクトリにあるSample12.htmlファイルをブラウザで確認してみよう。

このタグは、書いた説明文がそのまま表示されるだけである。

@throws、@exceptionタグ

@throwsタグは、発生する可能性がある例外に関する説明を表示するときに使用する。また、@exceptionタグと@throwsタグは、タグ名が異なるだけで同じように使用する。

@throws class-name description

例外に関する説明を表示する。

記述位置 : メソッド
複数記述 : 可能
出力形式 : Throws

メソッド内で発生する例外について、例外クラス名と説明を入力する。使い方は次のとおりである。

/ **
 * コメントの説明文
 * 
 * @throws java.io.FileNotFoundException 指定されたファイルが見つかりません
 * /

クラス名はパッケージ名まで含めてすべて指定できるが、パッケージ名を省略した場合は次の順序で検索される。

1. 現在のクラスまたはインターフェイス
2. 外側を囲んでいるクラスとインターフェイス。もっとも近いものから検索する
3. スーパークラスとスーパーインターフェイス。もっとも近いものから検索する
4. 現在のパッケージ
5. importされたパッケージ、クラス、インターフェイス。import文の順序に従って検索する

複数の@throwsタグが指定された場合、それぞれ別の行で表示される。

@throws、@exceptionタグの実習

簡単な例を試してみよう。

import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * Javadocテスト用クラス
 */
public class Sample13 {

    /**
     * ファイルを書き込む
     *
     * @throws FileNotFoundException 指定されたファイルが見つかりません
     */
    public void writeToFile() throws FileNotFoundException {

    }

    /**
     * ファイルを読み込む
     *
     * @throws java.io.IOException 入出力関連
     * @throws java.lang.SecurityException セキュリティ関連
     */
    public void readFromFile() throws IOException, java.lang.SecurityException {

    }

    /**
     * ファイルを削除する
     *
     * @throws java.lang.SecurityException セキュリティ関連
     * @exception FileNotFoundException 指定されたファイルが見つかりません
     */
    public void deleteFile() throws SecurityException {

    }

    /**
     * ファイルを探す
     */
    public void searchFile() throws FileNotFoundException {

    }

}

上のソースコードをSample13.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample13.java

生成されたdocディレクトリにあるSample13.htmlファイルをブラウザで確認してみよう。

deleteFileメソッドでは、@exceptionタグで書いた項目も@throwsタグを書いたときと同じようにThrowsに表示されている。

また、searchFileメソッドは@throwsタグを書いていないが、発生する可能性がある例外もJavadocによって自動的に抽出され、表示されていることが分かる。

{@link}、{@linkplain}タグ

{@link}タグは、他のJavadocタグの中で参照リンクを表示する場合に使用する。これまでのタグはすべてブロックタグと呼ばれるが、このタグはインラインタグと呼ばれる。インラインタグは{}で囲んで使用し、コメントの説明文の中や、他のブロックタグ内の文字列の一部として使用できる。

{@linkplain}タグは、基本的な使い方は{@link}タグと同じである。他のJavadocタグで文字列を表示する位置に参照リンクを表示する場合に使用する。違いは、{@link}タグを使用する場合はリンク文字列がコードテキストとして表示されるのに対し、{@linkplain}タグの場合はリンクされた文字列が通常のテキストとして表示される点だけである。

{@link package.class#member label}

ブロックタグ内の説明文や文字列部分で参照リンクを表示する。

記述位置 : 概要、パッケージ、クラス、インターフェイス、フィールド、メソッド
複数記述 : 可能

package.class#member形式で指定する別のメソッドへのリンクを作成する。リンクラベルとして指定されたlabelが表示されるが、labelは任意である。省略した場合は対象メソッド名で表示される。基本的な使い方は@seeタグと同じである。

/ **
 * コメントの説明文
 * 次のメソッド {@link Sample14#setSize(int, int) setSize} を参照
 * /

パッケージ名を省略した場合にどのようにリンクを検索するかについては、@seeタグ（参照リンク）を参照してほしい。

{@link}、{@linkplain}タグの実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス
 */
public class Sample14 {

      /**
       * 名前を設定する
       * 戻り値は {@link Sample14#getName() getName} を参照
       *
       * @param name 名前
       */
      public void setName(String name){

      }

      /**
       * 名前を返す
       * 設定は {@link #setName(String)} を参照
       *
       * @return 名前をStringで返す
       */
      public String getName(){
          return null;
      }

}

上のソースコードをSample14.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample14.java

生成されたdocディレクトリにあるSample14.htmlファイルをブラウザで確認してみよう。

まず、{@link}タグと{@linkplain}タグの違いを確認してみよう。上の文は{@link}タグで書かれているためコード文字として表示されており、下の文は{@linkplain}タグで書かれているため通常の文字フォントで表示されている。

コードフォントはHTMLの<code>...</code>タグで囲まれた場合に適用されるフォントであり、通常の文字フォントはこのHTMLタグで囲まれていないため、表示の見た目が異なる。リンクとして表示される点は同じである。

このように、{@link}タグと{@linkplain}タグは説明文にインラインリンクを作成するときに使用し、リンクを参照として別枠で表示する場合は@seeタグを使用する。

{@code}タグ

{@code}タグは、Javadocにサンプルコードを書くときに使用する。

{@code source-code}

サンプルコードを表示する。

記述位置 : 概要、パッケージ、クラス、インターフェイス、フィールド、メソッド
複数記述 : 可能

説明にサンプルコードを添付するときに使用する。使い方は次のとおりである。

/**
 * コメントの説明文
 * 
 * <pre>
 * {@code
 * Foo foo = new Foo();
 * foo.foo();
 * }
 * </pre>
 */

説明文にサンプルコードを添付する場合、{@code}タグだけを使用してもよいが、改行が必要なときはHTMLの<pre>タグも一緒に使用する必要がある。

{@code}タグの実習

簡単な例を試してみよう。

/**
 * Javadocテスト用クラス<br>
 *
 * <pre>
 * {@code
 * Foo foo = new Foo();
 * foo.foo();
 * }
 * </pre>
 */
public class Sample15 {

}

上のソースコードをSample15.javaというファイル名で保存し、保存したディレクトリで次のように実行する。

$ javadoc -d doc Sample15.java

生成されたdocディレクトリにあるSample15.htmlファイルをブラウザで確認してみよう。

このようにコードフォントで表示されている。コードフォントはHTMLの<code>...</code>タグで囲まれて適用されるフォントである。