Menu
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?
976
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.
The @inheritdoc tag indicates that a symbol should inherit its documentation from its parent class. Any other tags that you include in the JSDoc comment will be ignored. This tag is provided for compatibility with Closure Compiler.
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.
146
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
