Details of difference between @see and @inheritDoc
I have looked over JavaDoc reference, and while I understand basic difference between @see (various links) and {@inheritDoc} (export of superclass JavaDoc comment), I need clarification on how things actually implemented.
In Eclipse IDE when I select “Generate Element Comments” for the inherited method (from interface, or toString() override, and so forth) it creates following comment
/* (non-Javadoc)
* @see SomeClass#someMethod()
*/
If I am required to produce JavaDoc should I leave it at that, replace @see with {@inheritDoc}, or turn it in bona fide JavaDoc as such:
/**
* {@inheritDoc}
*/
And when I do that, should I still keep the class#method flag?
Answer
First of all, you should remove the original eclipse template because it is just noisy junk. Either put meaningful docs in or don't put anything at all. But useless restating of the obvious using IDE templates just clutters the code.
Second, if you are required to produce javadoc, then you have to make the comment start with /**. Otherwise, it's not javadoc.
Lastly, if you are overriding then you should use @inheritDoc (assuming you want to add to the original docs, as @seh noted in a comment, if you just want to duplicate the original docs, then you don't need anything). @see should only really be used to reference other related methods.