How to document a method that overrides another method?

Question

I always wondered how to document a method that overrides a message from a base class. Normally I add a java doc to each public method and to some private, protected methods.

But autogenerating a documentation block for an override method in eclipse produces something like this:

/*
 * (non-Javadoc)
 * 
 * @see javax.swing.JComponent#paintComponent(java.awt.Graphics)
 */

Is this a good way to document the override? Should I inherit/copy the documentation from the base class?

What are you doing as a documentation for this special case? I would like to have an overview of practices that are used.

Answer 1

Every method - private, protected public - should be documented describing what it does. Forget about inheriting documentation from a base class - you can include a link to it if you like, but as long as the information is there that it overrides an inherited method then the other person is free to look it up for themselves. DRY - don't repeat yourself - document the base class method in one place only.

I don't even think it is good to document which method it overrides, because that can change and it will be hard to keep it up to date if you insert new classes in the hierarchy between your class and the base class. Simply the information that it overrides an inherited method is sufficient.

If your methods are too complex to document in a few lines of comments, then they are probably too complex and should be refactored.

Answer 2

including the @Override annotation should be enough to send a curious developer to the super.