APIのドキュメントコメントの作成方法

古典を読む——《Effective Java》09
APIを実際に使用できるようにするには、ドキュメントを作成する必要があります.JavaはJavadocツールを提供し、APIのドキュメントの作成を容易にします.Javadocは、特殊な形式のドキュメントコメントを使用して、ソースコードに基づいてAPIドキュメントを自動的に生成します.

共通規則

事例説明

より多くの使い方

汎用ルール

は、エクスポートされたクラス、インタフェース、コンストラクタ、メソッド、およびドメイン宣言ごとにドキュメントコメントを追加する必要があります.クラスがシーケンス可能である場合は、そのシーケンス番号形式でドキュメントを記述する必要があります.

メソッドのドキュメント注釈は、クライアントとの間の約束を簡潔に記述しなければならない.この約束はこの方法がどのようにしたのかを説明すべきで、それがどのようにしたのかを説明するのではありません.ドキュメントコメントは、このメソッドのすべての前提条件と後置条件を列挙する必要があります.前提条件とは、お客様がこの方法を呼び出すために満たさなければならない条件を指す.バックグラウンド条件とは、呼び出しが正常に完了した後に、どの条件が満たされなければならないかを意味します.一般に、前提条件は、@throwsタグによって隠された異常を記述し、影響を受けるパラメータのいくつかの@paramタグに前提条件を指定することもできる.このほか、ドキュメントコメントでは、メソッドの副作用についても説明する必要があります.副作用とは、メソッドの実行後にシステム状態に与える影響を指します.たとえば、メソッドがバックグラウンドスレッドを起動した場合、ドキュメントで説明する必要があります.最後に、ドキュメントコメントは、クラスまたはメソッドのスレッドセキュリティについても記述する必要があります.

ケース・ノート
次の短いドキュメントコメントでは、一般的な使い方を説明します.

/**
 * Returns the element at the specified position in this list.
 *
 * 
This method is not guaranteed to run in constant
 * time. In some implementations it may run in time proportional
 * to the element position.
 *
 * @param index index of element to return; must be
 *        non-negative and less than the size of this list
 * @return the element at the specified position in this list
 * @throws IndexOutOfBoundsException if the index is out of range
 *         ({@code index < 0 || index >= this.size()})
 */
E get(int index);

ドキュメントコメントは/**で始まる必要があります.そうしないと、Javadocは認識できません.

ドキュメント注釈の最初の文を概要として説明します.サマリー記述は、ターゲット要素の機能を独立して記述する必要があります.同じクラスまたはインタフェースの任意の2つのメンバーまたはコンストラクタは、同じサマリー記述を持つべきではありません.リロード方法でもダメです.

各パラメータには@paramラベルがあり、ラベルの後ろの最初の単語はパラメータ名であり、次にパラメータの解釈と要求である.

がタイプ非voidを返す方法には、@returnのラベルがあり、戻り値が表す内容を記述しなければならない.

この方法が投げ出す可能性のある各異常は、検出された異常であっても非検出された異常であっても、@throwsラベルに対応しなければならない.ラベルの後ろの最初の単語は異常タイプで、次はifで始まるべきで、この異常がどのような場合に投げ出されるかを説明します.@param、@return、および@throwsは、いずれもピリオドで終了しない.

@codeタグは、コードを表示する必要がある任意の場所で使用することができ、このタグに囲まれたコンテンツは特殊なフォントで表示され、コンテンツはHTML解析されません.

慣例によれば、「this」という単語は、インスタンスメソッドのドキュメント注釈に使用される場合、常にメソッド呼び出しが存在するオブジェクトを指すべきである.

は、@literalタグでHTMLメタ文字を含む文を示すことができる.表示スタイルを変更しない以外は@codeと同じです.

その他の使用方法
汎用、列挙、注釈のドキュメント注釈にさらに注意する必要があります.

汎用ドキュメント注釈は、すべてのタイプのパラメータを説明する必要があります.

/**
   * An object that maps keys to values. A map cannot contain
   * duplicate keys; each key can map to at most one value.
   *
   * (Remainder omitted)
   * 
   * @param  the type of keys maintained by this map
   * @param  the type of mapped values
   */
public interface Map {
    // Remainder omitted
}

列挙のためにドキュメントを作成する場合は、ドキュメントに定数が記載されていることを確認します.

/**
   * An instrument section of a symphony orchestra.
   */
public enum OrchestraSection {
    /** Woodwinds, such as flute, clarinet, and oboe. */
    WOODWIND,

    /** Brass instruments, such as french horn and trumpet. */
    BRASS,

    /** Percussion instruments, such as timpani and cymbals. */
    PERCUSSION,

    /** Stringed instruments, such as violin and cello. */
    STRING;
}

注記タイプのドキュメントを作成する場合は、すべてのメンバーとタイプ自体がドキュメントに記載されていることを確認します.動詞フレーズを使用して、プログラム要素がこのようなタイプの注釈を持っている場合、それがどういう意味を表すかを説明します.

/**
   * Indicates that the annotated method is a test method that
   * must throw the designated exception to succeed.
   */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**
     * The exception that the annotated test method must throw
     * in order to pass. (The test is permitted to throw any
     * subtype of the type described by this class object.)
     */
    Class extends Exception> value();
}

また、クラスがスレッドセキュリティであるかどうかは、ドキュメントでスレッドセキュリティレベルを説明する必要があります.クラスがシーケンス可能である場合は、ドキュメントにシーケンス形式を説明する必要があります.Javadocにはメソッドアノテーションを継承する機能があり、API要素にドキュメントアノテーションがない場合、Javadocは最も適切なインタフェースまたはスーパークラスのドキュメントアノテーションを自動的に検索し、インタフェースはスーパークラスより優先します.
著者または文集「Effective Java」に注目し、最新のリリース記事を最初に入手します.
参考資料
How to Write Doc Comments for the Javadoc Tool Oracle