Win a copy of Programmer's Guide to Java SE 8 Oracle Certified Associate (OCA) this week in the OCAJP forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

javadoc comments

 
Chiji Nwankwo
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
I have an interface, A, with methods a, b, c and a class, AImpl, that implements interface A. Class AImpl provides implementations for inherited methods, a, b, c. Should the javadoc comments for methods a, b, c be placed in the interface or in the class.
Please can anyone tell me what the correct way is. I'm trying not clutter my assignment with too much comments, so I don't want put comments where they are not needed.
Thanks,
chiji
 
Valentin Crettaz
Gold Digger
Sheriff
Posts: 7610
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Should the javadoc comments for methods a, b, c be placed in the interface or in the class.
Please have a look at How to Write Doc Comments for the Javadoc Tool document. Then, browse to the "Descriptions - Automatic re-use of method comments". They explain how to reuse comments written in an interface.
As a convenience the explanations are pasted below:

Automatic re-use of method comments
You can avoid re-typing doc comments by being aware of how the Javadoc tool duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases:
When a method in a class overrides a method in a superclass
When a method in an interface overrides a method in a superinterface
When a method in a class implements a method in an interface
In the first two cases, if a method m() overrides another method, The Javadoc tool will generate a subheading "Overrides" in the documentation for m(), with a link to the method it is overriding.
In the third case, if a method m() in a given class implements a method in an interface, the Javadoc tool will generate a subheading "Specified by" in the documentation for m(), with a link to the method it is implementing.
In all three of these cases, if the method m() contains no doc comments or tags, the Javadoc tool will also copy the text of the method it is overriding or implementing to the generated documentation for m(). So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m(). If you add any documentation comment or tag to m(), the "Overrides" or "Specified by" subheading and link will still appear, but no text will be copied.
 
Chiji Nwankwo
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you for your response.
I guess my question was more in line with whether or not the examiner will look for comments in an interface, if he/she doesn't find comments in its implementing class.
Regards,
chiji
 
Valentin Crettaz
Gold Digger
Sheriff
Posts: 7610
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
That's what I tried to explain. You don't need to repeat the same comments in the implementing classes since the javadoc tool handles that for you. If you do repeat comments, not only will this perceived as clutter by the assessor, but also the latter may think that you don't know how to use the javadoc tool, which can be much more discriminative.
 
Chiji Nwankwo
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
thanks
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic