• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Javadoc standards

 
Jonathan Pengelly
Greenhorn
Posts: 19
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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,
Jonathan
 
Mogens Nidding
Ranch Hand
Posts: 77
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi!
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
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic