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

Question

私はメソッド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(); 
} 

それが正しいですか私はCLASSのコメントに他のものを追加する必要があります：私はクラスをこのようにコメントしていますか？

Answer 1

はい、インターフェイスの背景と、呼び出し元と実装者の両方の契約内容を明確にするために、適切なJavadocコメントを記述する必要があります。

はjava.util.List

Answer 2

いいえ、メソッドのJavaDocコメントを指定していません。インターフェースを使用しているか実装している人は、そのメソッドが何を意味するのかを知ることを意味していますか？発信者と実装者：発信者を目指しているほとんどのJavaDocとは異なり、インターフェイスのドキュメントは、2人の観客を持っていることを念頭に置いて

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

ベア：あなたは適切なJavaDocの記述を使用する必要があります。 の両方の面が期待できることと、どのように行動すべきかについて明確にする必要があります。はい、これはうまくやるのは難しいです:(

EDIT：トップレベルのコメントの面では：。個人的に

• それはIMOまれに有用だと私は、@authorタグを取り除くと思います（通常は実際は（だけではなく日付）意味のあるバージョン管理ポリシーを持っているあなた、私は@sinceタグを取り除くしたい場合を除き、ソース管理に探して）...
• より適切である。
は、ソースを述べるにはポイントはありません
• ファイル
• 「次のメソッドを持つインターフェイスクラス」の説明は意味がありませんとは矛盾しています（インターフェイスはクラスではありません）。 JavaDocを読んでいる人は、すでにメソッドのリストを見ることができます。あなたはここに余分な情報を提供しようとしているはずです。

通常のクラスのドキュメントの場合と同様に、インターフェイスのドキュメントには、オブジェクトのより大きなスキームにおける役割、おそらくその使用方法の例など、その種類の目的を記載する必要があります。一般的に合理的なJavaDoc用のJDK。