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

Question

Assume I have an interface as follows.

public interface MyInterface{

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

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

A concrete class implements these methods. Now do the methods in the concrete class also needs to define the javadocs on top of its method definition? 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.

what is the standard practice for this?

Answer 1

You can use {@inheritDoc} to inherit the documentation of the interface and just add extra comments if you think they are significant and relevant extra info for the specific implementation.

Only use @inheritDoc if you intend to add to the original superclass/interface documentation. If you only want a copy, Javadoc will take care of that. It will see that the superclass documentation applies to the subclass's overridden method because the subclass provided no additional documentation.

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