112

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?

reevesy
  • 3,452
  • 1
  • 26
  • 23
theUg
  • 1,284
  • 2
  • 9
  • 14

1 Answers1

164

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.

jtahlborn
  • 52,909
  • 5
  • 76
  • 118
  • 94
    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. – seh Nov 11 '12 at 01:11
  • 8
    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. – randominstanceOfLivingThing May 29 '14 at 17:34
  • 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. – Benjamin Marwell Mar 20 '20 at 07:49