如果实现方法的接口具有 JavaDoc 注释，则实现方法是否应具有 JavaDoc 注释

Question

假设我有如下界面。

public interface MyInterface{

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

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

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

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

Answer 1

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

如果您打算添加到原始 superclass/interface 文档，请仅使用@inheritDoc。如果您只需要一份副本，Javadoc 会处理。它将看到超类文档适用于子类的重写方法，因为子类没有提供额外的文档。

{@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

Answer 2

Now do the methods in the concrete class also needs to define the javadocs on top of its method definition?

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

I see some people just copying the same javadoc definition to the concrete class's implemented methods. I don't see this as a good practice because if we are to change the doc definition we need to change it in multiple places.

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

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

/**
 *
 */

Answer 3

如果

，您应该提供具体实施的评论

接口的注释过于笼统，没有充分说明具体的实现
具体实现放宽了接口的任何先决条件
具体实现比接口具有更严格（更窄）的post条件。

如果实现方法的接口具有 JavaDoc 注释，则实现方法是否应具有 JavaDoc 注释

Should implementing methods have JavaDoc commentary if the interface they implement has JavaDoc commentary

java

javadoc