web-dev-qa-db-ja.com

JavaDocインターフェースのコメント

メソッドx、y、zを持つインターフェイスAがあります。私はこのようにクラスにコメントしています：

/**
 * 
 * A.Java
 * Interface class that has the following methods.
 * 
 * @author MyName
 * @since mm-dd-yyyy
 */

public interface A {

    //method description for x
    void x();

    //method description for y
    void y();

    //method description for z
    void z();
}

それは正しいですか、それともクラスコメントに他のものを追加する必要がありますか？

javainterfacecommentsjavadoc
8
FranXh

はい、インターフェイスの背後にある動機と、呼び出し元と実装者の両方のコントラクトを明確に指定するために、インターフェイスに適切なJavadocコメントを書き込む必要があります。

Java.util.List のような例については、JDKコードのいくつかのインターフェースを見てください。

12
Peter Svensson

いいえ、メソッドにJavaDocコメントを指定していません。誰かがインターフェースを使用または実装することは、メソッドが何を意味するのかを知ることをどのように意味しますか？適切なJavaDocの説明を使用する必要があります。

/**
 * This method fromulgates the wibble-wrangler. It should not be called without
 * first saturating all glashnashers.
 */
void x();

callersを対象とするほとんどのJavaDocとは異なり、インターフェースのドキュメントには、呼び出し元と実装者の2つの対象者がいることに注意してください。 両方側が期待できることと、それらがどのように動作するかを明確にする必要があります。はい、これはうまくやるのは難しいです:(

編集：トップレベルのコメントに関して：

  • 個人的には、@authorタグはめったに役に立たないIMOなので、削除します。 （通常、ソース管理を調べる方が適切です...）
  • 実際には意味のあるバージョン管理ポリシー（日付だけでなく）がない限り、@sinceタグを削除します。
  • ソースファイルを記載しても意味がありません
  • 「次のメソッドを持つインターフェイスクラス」の説明は無意味ですおよび矛盾しています（インターフェイスはクラスではないため）。 JavaDocを読んでいる人は誰でも、メソッドのリストをすでに見ることができます。ここで追加情報を提供しようとしているはずです。

通常のクラスのドキュメントと同様に、インターフェイスのドキュメントには、型の目的（より壮大なスキームでの役割、おそらく使用方法の例など）を記載する必要があります。一般的に合理的なJavaDocについては、JDKの例を参照してください。 。

38
Jon Skeet