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. I usually add a java document to each public method and to some private protected methods.

But auto-generating the documentation block for the override method in eclipse leads to the following:

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

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

What do you do as documentation for this special case? I would like to familiarize myself with the practice that is being used.

Answer 1

Each method - private, protected public - should be documented, describing what it does. Forget about inheriting documentation from the base class - you can include a link to it if you want, but as long as there is information that it overrides the inherited method, then another person can view it on their own. DRY - don't repeat yourself - write the base class method in only one place.

I don’t even think it’s good to document which method it redefines, because it can change, and it will be difficult to update it if you introduce new classes in the hierarchy between your class and the base class. Just enough information that it overrides the inherited method.

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

Answer 2

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