次のようなインターフェースがあるとします。実装しているメソッドがJavaDocの解説を持っているかどうかは、実装するインターフェースにJavaDoc解説がある場合
public interface MyInterface{
/**
* This method prints hello
*/
void sayHello();
/**
* This method prints goodbye
*/
void sayGoodBye();
}
具体的なクラスは、これらのメソッドを実装します。今具体クラスのメソッドは、メソッド定義の上にjavadocを定義する必要がありますか？具体的なクラスの実装されたメソッドに同じjavadoc定義をコピーする人もいます。ドキュメントの定義を変更する必要がある場合は、複数の場所で変更する必要があるため、これは良い方法ではありません。
これの標準的な慣行は何ですか？
{@inheritDoc}を使用してインターフェイスのドキュメントを継承し、特定の実装に関する重要かつ関連する追加情報だと思われる場合は、追加のコメントを追加するだけです。
元のスーパークラス/インタフェースのドキュメントに追加する場合にのみ、@inheritDocを使用してください。コピーだけが必要な場合は、Javadocがそれを処理します。サブクラスが追加のドキュメントを提供しなかったため、スーパークラスのドキュメントはサブクラスのオーバーライドされたメソッドに適用されることがわかります。
{@inheritDoc}- 「最も近い」継承可能クラスまたは実装可能なインターフェイスから、このタグの場所にある現在のドキュメントコメントにドキュメントを継承（コピー）します。これにより、より一般的なコメントを継承ツリーよりも上に書くことができ、コピーされたテキストの周りに書くことができます。
http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc
あなたはそれをする必要はありません。そして、実装に固有のマテリアルを追加し、同じテキストブロックに継承されたマテリアルと追加されたマテリアルの両方を持たない限り、それを行うことはほとんどありません。 –
は今具象クラスのメソッドは、そのメソッドの定義の上にjavadocを定義する必要があるのですか？
いいえ、すでに指定されています。具体的なメソッドは、Javadocのインタフェースとまったく同じものを行う必要があります。
具体的なクラスの実装されたメソッドに同じjavadoc定義をコピーする人がいます。ドキュメントの定義を変更する必要がある場合は、複数の場所で変更する必要があるため、これは良い方法ではありません。
あなたは正しいです。彼らはこれをしてはいけません。
非常にまれな場合を除いて、具体的なメソッドが既にインターフェイスJavadocより多くの記述を必要とする場合を除いて、@inheritDocを使用しないでください。時間のほとんどは、あなたがいなくても、まったくのJavadocを提供してはならない。
/**
*
*/
あなた
メソッドを宣言するインターフェイスでは、メソッドの概要を知ることができます。実装では、必要に応じて、メソッドで何が正確に実行されているかを示すメソッドを段階的に説明することができます。理想的には、適切なコーディング標準を使用する場合、そのような詳細な説明を与える必要はありません。 – Raghuveer
あなたはインターフェイスメソッドjavadocsを簡潔にすると言っていますか？ – DesirePRG
はい、また、APIが何をすると考えているかを読者に理解させるのに十分説明的です。 – Raghuveer