java - 如果实现方法的接口(interface)具有 JavaDoc 注释，则实现方法是否应具有 JavaDoc 注释

Question

假设我有一个界面如下。

public interface MyInterface{

 /**
 * This method prints hello
 */
  void sayHello();

  /**
  * This method prints goodbye
  */
  void sayGoodBye();
}

具体类实现这些方法。现在，具体类中的方法是否还需要在其方法定义之上定义 javadoc？我看到有些人只是将相同的 javadoc 定义复制到具体类的实现方法中。我不认为这是一个好的做法，因为如果我们要更改文档定义，我们需要在多个地方进行更改。

这方面的标准做法是什么？

Answer 1

您可以使用 {@inheritDoc} 来继承接口(interface)的文档，如果您认为它们对特定实现很重要且相关的额外信息，则只需添加额外的注释。

只有在您打算添加到原始父类(super class)/接口(interface)文档时才使用@inheritDoc。如果您只需要一份副本，Javadoc 会处理。它将看到父类(super class)文档适用于子类的重写方法，因为子类没有提供额外的文档。

{@inheritDoc} - Inherits (copies) documentation from the "nearest" inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text.

http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc