Should I use a "non-Javadoc" comment?

Question

I implemented my own method defined in an interface. However when I try to add Javadoc to this method Eclipse gave me a comment like this:

/* (non-Javadoc)
 * @see javax.servlet.ServletContextListener#contextInitialized(javax.servlet.ServletContextEvent)
 */

Actually, I really need to add some comment to this method. What should I do?

Do you require an interface? If you are implementing methods (I assume public methods) you may want to use an abstract class? — Terrell Plotzki, Jun 14 '11 at 01:50
Closely related: http://stackoverflow.com/questions/4597329/does-non-javadoc-have-a-well-understood-meaning — Ciro Santilli OurBigBook.com, Feb 20 '15 at 17:32

score 14 · Answer 1 · answered Jun 14 '11 at 02:00

The idea of adding a non-javadoc comment here is that in the generated javadoc the comment from the inherited method will be copied, which might be enough - and better than if you had an empty /** */ comment. At the same time, you can use the link in the source code to look up the method. And as said by Ken, you can always change it.

If you want to include the interface's documentation, use {@inheritDoc} in your comment.

score 12 · Answer 2 · edited Jun 14 '11 at 01:54

12

Eclipse gave you something, but you can feel free to change it. Change it into a javadoc comment by adding the second star to make it a /** at the beginning, then write whatever you want just like you do with the other javadoc comments. Eclipse won't get in your way or insist you change things back -- it's just giving you some boilerplate to work with.

edited Jun 14 '11 at 01:54

Asaph

159,146
25
197
199

answered Jun 14 '11 at 01:49

Ken Bloom

57,498
14
111
168

12

IMO, this particular piece boilerplate is a total waste of space ... sigh. – Stephen C Jun 14 '11 at 02:17

Should I use a "non-Javadoc" comment?

2 Answers2

Linked