Details of difference between @see and @inheritDoc

Question

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?

Solution

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.

Comments

[subrat71]

You should only use @inheritDoc if you intend to add to the original superclass documentation. If you merely want it to be duplicated, Javadoc will do that already, noting that the superclass documentation applies to the subclass's overridden method because the subclass provided no additional documentation.

[randominstanceOfLivingThing]

I generated the docs with and without @inheritDoc and dont see any difference. Even without the @inheritDoc, I see that the Javadoc of derived class was appended to the base class.

[Benjamin Marwell]

I came here because checkstyle complains "method does not seem to be designed for extension". A good idea might be to use @inheritDoc and then add some implementation specific documentation, e.g. how it implements/overwrites the parent method, and especially WHY it does it the way it does.