jQuery in Action, 3rd edition
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc standards Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc standards" Watch "Javadoc standards" New topic

Javadoc standards

Jonathan Pengelly

Joined: Jan 17, 2004
Posts: 19
Hi all,
I was wondering what the standard technique is when commenting a method that is written in a class because it is defined in an interface that is implemented by that class?
For example, how do you comment the create method in the Data class when you have already documented it in the DBMain interface.
Currently, I have just copied the comments word for word.
Thanks for any help,
Mogens Nidding
Ranch Hand

Joined: Mar 08, 2004
Posts: 77
You can omit javadoc altogether for the overriding/implementing method entirely; The Javadoc tool will copy it from the superclass/interface.
For most of your javadoc questions, you will find How to Write Doc Comments most useful. I found the answer to your question under "Automatic re-use of method comments".
As far as I know, this is as standard as it gets. Also personally, I would surely avoid copying the documentation word-by-word at all costs, since the copies are just begging to get out of sync.
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
Hi Jonathan,
I agree with what Nicky wrote.
There may be some circumstance under which you wish to inherit the javadoc from a parent, but wish to add some extra text to the comment. For example:

By doing this you get the ability to inherit the javadoc from the implemented interface, but can also add more commentary if necessary. If don't need to add more commentary you're better off omitting the javadoc comment entirely (as Nicky advised).
[ March 08, 2004: Message edited by: George Marinkovich ]

Regards, George
I agree. Here's the link: http://aspose.com/file-tools
subject: Javadoc standards
jQuery in Action, 3rd edition