Is it correct practice to add Javadoc comments in Interface and add non Javadoc comments in the implementation?
Most IDEs generate non JavaDoc comments for implementations when you auto generate comments. Shouldn't the concrete method have the description?
Both the implementation and the interface should have javadoc. With some tools, you can inherit the documentation of the interface with the @inheritDoc keyword.
/**
* @inheritDoc
*
* This implementation is very, very slow when b equals 3.
*/
public foo(int b)
{ ... }
For the sake of generated javadoc yes it does matter. If you declare references to a concrete implementation using only the interface then it doesn't since interface's methods will be retrieved by the IDE.
@see generates a link to the description in the interface. But i think it is good to add some details about the implementation too.
Somewhat good practice is to put
/**
* {@inheritDoc}
*/
as implementation's javadoc (unless there's something extra to be explained about the implementation's details).
We use java doc in both situations.
In interfaces, javadoc is a must. Quite hard to use it, without any knowledge what it does.
In the implementation its useful for auto complete and new colleagues.
Sjoerd correctly says that both interface and implementation should have JavaDoc. The interface JavaDoc should define the contract of the method - what the method should do, what inputs it takes, what values it should return, and what it should do in cases of error.
The implementation documentation should note extensions or restrictions on the contract, and also appropriate details of the implementation, especially performance.
For methods that are implementation only (not overrides), sure, why not, especially if they are public.
If you have an overriding situation and you are going to replicate any text, then definitely not. Replication is a surefire way of causing discrepancies. As a result, users would have a different understanding of your method based on whether they examine the method in the supertype or the subtype. Use @Inheritdoc or don't provide a documentation - The IDEs will take the lowest available text to use in their Javadoc view.
As an aside, if your overriding version adds stuff to the documentation of the supertype, you could be in a world of trouble. I studied this problem during my PhD and found that in general folks will never be aware of the extra information in the overriding version if they are invoking through a supertype.
Addressing this problem was one of the major feature of the prototype tool that I built - Whenever you invoked a method, you got an indication if its target or any potential overriding targets contained important information (e.g., a conflicting behavior). For instance, when invoking put on a map, you were reminded that if your implementation is a TreeMap, your elements need to be comparable.