Best practice for JavaDocs - interface, implementation, or both?

Question

I have a DAO interface and a DAO implementation. JavaDocs in an interface is what Netbeans displays for a client that implements DAO methods.

Obviously, I will need to support JavaDocs in the interface. But what about its implementation? On the one hand, they are convenient there, but, on the other hand, this is duplication and requires that they be supported in two places.

Just wondering what other Java developers are doing.

Answer 1

In my project, Eclipse automatically generates documentation, as shown below:

/* (non-Javadoc) * @see com.comp.SomeInterface#method(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse) */ @Override public void method(HttpServletRequest arg0, HttpServletResponse arg1) throws Exception { // TODO Auto-generated method stub } 

We created javadoc using the Ant task, so it creates a link to the interface.

Answer 2

If the implementation method does not provide its own Javadoc, there will still be a link to the interface method documents. I never understood why Eclipse inserts /* (non-Javadoc) @see ... */ , since Javadocs automatically references interface documents.

Example:

 public interface Named { /** Returns the name. */ public String getName(); } public class Thing implements Named { // note no Javadocs here public String getName() { return "thing"; } } 

After running javadoc , Thing.getName Javadocs:

 getName public java.lang.String getName() Description copied from interface: Named Returns the name. Specified by: getName in interface Named 

Answer 3

The interface should have all the information about the contract, basically what this method does, a description of the parameters, return values, etc.

If there is no additional information that is not clear from the interface description (this rarely happens), then the implementation documentation should just refer to the interface method.

This is the format that I found most suitable both from the developer and from the client side of the fence.