7

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.

Janusz
  • 187,060
  • 113
  • 301
  • 369
  • duplicate: http://stackoverflow.com/questions/1081408/java-documentation-override-method-does-not-inheritdoc – AlbertoPL Jul 04 '09 at 03:50
  • 1
    you edited a question that is pretty much exactly the same as the one you just asked? awesome, dude. – geowa4 Jul 04 '09 at 03:53
  • Not really... Here's your +1 back – colithium Jul 04 '09 at 03:54
  • I asked this question in a commentar to the question but then I figured my question is more general and having a bunch of people commenting on my quetion in the comment would be of no use to the person who asked a more special question – Janusz Jul 04 '09 at 03:57
  • Other question asks how to inherit java docs. This question asks for best practice – colithium Jul 04 '09 at 04:00

2 Answers2

10

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.

Larry Watanabe
  • 10,126
  • 9
  • 43
  • 46
1

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

akf
  • 38,619
  • 8
  • 86
  • 96
  • 1
    I disagree - it will slow me down when reading the code to have to click through. I prefer at least a small note WITH the Override. I then know immediately what the method does, and if I am curious about the full details, I can click through. – Richard Le Mesurier Jul 12 '12 at 07:11