Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

JavaDoc for methods from interfaces

 
David Abramowicz
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all.

Do you think it is necessary to document with JavaDoc methods that are from interfaces, other than with the @see tag? For instance, in one of my controllers, I have an actionPerformed method, and the JavaDoc generated for it is:

actionPerformed
public void actionPerformed(java.awt.event.ActionEvent event)Specified by:
actionPerformed in interface java.awt.event.ActionListener
See Also:
ActionListener.actionPerformed(java.awt.event.ActionEvent)

So do you reckon that's sufficient?

Cheers /Dave
 
Valentin Tanase
Ranch Hand
Posts: 704
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi David,

It appears to me that you should provide complete javadoc even to your interfaces. The reason behind in my opinion is that an interface provides generic functionality that could be implemented (in different ways) by several classes. On the other hand if two classes A and B implement your interface, how are you documenting the methods: referring to corresponding methods in A, B, or maybe both? Besides an interface might not be (and shouldn�t be) aware of the classes that implement it.
Finally I can tell you for sure what not to do: I personally copied the javadocs from the interface to the implemented classes, doing only very cosmetically changes and I got a very low score for the documentation.
Regards.
 
peter wooster
Ranch Hand
Posts: 1033
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by David Abramowicz:
Hi all.

Do you think it is necessary to document with JavaDoc methods that are from interfaces, other than with the @see tag? For instance, in one of my controllers, I have an actionPerformed method, and the JavaDoc generated for it is:

actionPerformed
public void actionPerformed(java.awt.event.ActionEvent event)Specified by:
actionPerformed in interface java.awt.event.ActionListener
See Also:
ActionListener.actionPerformed(java.awt.event.ActionEvent)

So do you reckon that's sufficient?

Cheers /Dave


If your method implements a method described in the Java API, you might want to say what it does, or use an anonymous inner class, in which case you probably don't need the javadoc.

If it implements a method described in one of your interfaces you can use

to have javadoc include the documentation from the parent interface.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic