aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes JavaDoc for methods from interfaces Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Spring in Action this week in the Spring forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "JavaDoc for methods from interfaces" Watch "JavaDoc for methods from interfaces" New topic
Author

JavaDoc for methods from interfaces

David Abramowicz
Ranch Hand

Joined: Dec 10, 2004
Posts: 56
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

Joined: Feb 17, 2005
Posts: 704
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.


I think, therefore I exist -- Rene Descartes
peter wooster
Ranch Hand

Joined: Jun 13, 2004
Posts: 1033
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.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: JavaDoc for methods from interfaces