Win a copy of Microservices in Action this week in the Web Services forum!
  • 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 all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Bear Bibeault
  • Devaka Cooray
  • Liutauras Vilda
  • Jeanne Boyarsky
Sheriffs:
  • Knute Snortum
  • Junilu Lacar
  • paul wheaton
Saloon Keepers:
  • Ganesh Patekar
  • Frits Walraven
  • Tim Moores
  • Ron McLeod
  • Carey Brown
Bartenders:
  • Stephan van Hulst
  • salvin francis
  • Tim Holloway

Javadoc standards  RSS feed

 
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
 
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.
 
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 ]
 
It is sorta covered in the JavaRanch Style Guide.
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!