如果它们实现的接口具有JavaDoc注释

Question

假设我有一个如下界面。

public interface MyInterface{

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

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

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

这是什么标准做法？

Answer 1

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

如果您打算添加到原始超类/界面文档，则仅使用@inheritDoc。如果您只想要一份副本，Javadoc将负责处理。它将看到超类文档适用于子类的重写方法，因为子类没有提供其他文档。

  

{@inheritDoc} - 将“最近的”可继承类或可实现的接口的文档继承（复制）到此标记位置的当前doc注释中。这允许您在继承树的更高位置编写更多通用注释，并在复制的文本周围编写。

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

Answer 2

  

现在具体类中的方法还需要在方法定义的基础上定义javadoc吗？

没有。已经指定了。具体的方法应该完全按照Javadoc所说的那样做，而不是别的。

  

我看到有些人只是将相同的javadoc定义复制到具体类的实现方法中。我不认为这是一个好习惯，因为如果我们要更改文档定义，我们需要在多个地方更改它。

你是对的。他们不应该这样做。

你也不应该使用package，除非极少数情况下具体方法需要比Javadoc接口更多的描述。大多数时候你根本不应该提供任何Javadoc，甚至不提供：

@inheritDoc

Answer 3

如果

，应该为具体实施提供评论

• 界面的评论是如此通用，没有充分说明具体的实施
• 具体实现放宽了界面的任何前提条件
• 具体实施具有比界面更严格（更窄）的后置条件。