Javaドキュメンテーションコメント：Javadocとコメントタイプをマスター

Javaのコメントタイプ

Java言語は3種類のコメントをサポートしています：

番号	コメントと説明
1	/* text */ コンパイラは/*から*/までのすべてを無視します。
2	//text コンパイラは//から行末までのすべてを無視します。
3	/** documentation */ これはドキュメンテーションコメントで、一般的にdocコメントと呼ばれます。JDK javadocツールは、自動生成ドキュメントの作成時にdocコメントを使用します。

この章ではJavadocについて説明します。Javadocを使ってJavaコードの有用なドキュメントを生成する方法を見ていきます。

Javadocとは

JavadocはJDKに付属するツールで、事前定義されたフォーマットでドキュメントが記述されたJavaソースコードから、HTML形式のJavaコードドキュメントを生成するために使用されます。

以下はシンプルな例で、/*….*/内の行はJavaの複数行コメントです。同様に、//で始まる行はJavaの単一行コメントです。

例

/**
 * HelloWorldプログラムは単純に標準出力に
 * "Hello World!"を表示するアプリケーションを実装します。
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        // 標準出力にHello, World!を出力
        System.out.println("Hello World!");
    }
}

説明部分に必要なHTMLタグを含めることができます。例えば、以下の例では見出しに<h1>....</h1>、段落区切りに<p>を使用しています。

例

/**
 * <h1>Hello, World!</h1>
 * HelloWorldプログラムは単純に標準出力に
 * "Hello World!"を表示するアプリケーションを実装します。
 * <p>
 * プログラムに適切なコメントを付けることで、
 * よりユーザーフレンドリーになり、高品質なコードと見なされます。
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Javadocタグ

javadocツールが認識するタグは以下の通りです：

タグ	説明	構文
@author	クラスの作成者を追加	@author name-text
{@code}	テキストをコードフォントで表示し、HTMLマークアップやネストしたjavadocタグとして解釈しない	{@code text}
{@docRoot}	生成されたドキュメントのルートディレクトリから任意の生成ページへの相対パスを表す	{@docRoot}
@deprecated	このAPIを今後使用すべきでないことを示すコメントを追加	@deprecated deprecatedtext
@exception	生成ドキュメントにThrowsサブヘッダーを追加し、クラス名と説明テキストを表示	@exception class-name description
{@inheritDoc}	継承可能な最も近いクラスまたは実装可能なインターフェースからコメントを継承	直近のスーパークラスからコメントを継承
{@link}	指定されたパッケージ、クラス、または参照クラスのメンバ名のドキュメントを指す、表示テキストラベル付きのインラインリンクを挿入	{@link package.class#member label}
{@linkplain}	{@link}と同一だが、リンクラベルがコードフォントではなくプレーンテキストで表示される	{@linkplain package.class#member label}
@param	指定されたパラメータ名と説明を"Parameters"セクションに追加	@param parameter-name description
@return	説明テキスト付きの"Returns"セクションを追加	@return description
@see	参照を指すリンクまたはテキストエントリ付きの"See Also"ヘッダーを追加	@see reference
@serial	デフォルトのシリアライズ可能フィールドのドキュメントコメントで使用	@serial field-description | include | exclude
@serialData	writeObject()またはwriteExternal()メソッドで書き込まれるデータを文書化	@serialData data-description
@serialField	ObjectStreamFieldコンポーネントを文書化	@serialField field-name field-type field-description
@since	指定されたsince-text付きの"Since"ヘッダーを生成ドキュメントに追加	@since release
@throws	@throwsと@exceptionタグは同義	@throws class-name description
{@value}	静的フィールドのドキュメントコメントで{@value}を使用すると、その定数の値を表示	{@value package.class#field}
@version	-versionオプション使用時に、指定されたversion-text付きの"Version"サブヘッダーを生成ドキュメントに追加	@version version-text

実用例

以下のプログラムでは、ドキュメンテーションコメントで利用可能な重要なタグのいくつかを使用しています。要件に応じて他のタグも活用できます。

AddNumクラスについてのドキュメントはHTMLファイルAddNum.htmlとして生成されますが、同時にindex.htmlというマスターファイルも作成されます。

import java.io.*;

/**
 * <h1>Add Two Numbers!</h1>
 * AddNumプログラムは、与えられた2つの整数を単純に加算し、
 * 結果を画面に出力するアプリケーションを実装します。
 * <p>
 * <b>Note:</b> プログラムに適切なコメントを付けることで、
 * よりユーザーフレンドリーになり、高品質なコードと見なされます。
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class AddNum {
    /**
     * このメソッドは2つの整数を加算するために使用されます。
     * これはクラスメソッドの最もシンプルな形式で、
     * 様々なjavadocタグの使用法を示すだけです。
     * @param numA addNumメソッドの第1パラメータ
     * @param numB addNumメソッドの第2パラメータ
     * @return int numAとnumBの合計を返します。
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }

    /**
     * これはaddNumメソッドを利用するmainメソッドです。
     * @param args 未使用。
     * @return なし。
     * @exception IOException 入力エラー時。
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("Sum of 10 and 20 is :" + sum);
    }
}

上記AddNum.javaファイルをjavadocユーティリティで処理します：

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$

生成されたドキュメントはこちらで確認できます - AddNum。JDK 1.7を使用している場合、javadocは優れたstylesheet.cssを生成しないため、https://docs.oracle.com/javase/7/docs/api/stylesheet.css から標準スタイルシートをダウンロードして使用することを推奨します。