• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

JavaDoc for methods from interfaces

 
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 704
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Ranch Hand
Posts: 1033
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
He's my best friend. Not yours. Mine. You can have this tiny ad:
a bit of art, as a gift, the permaculture playing cards
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic