aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes javadoc comments 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 comments" Watch "javadoc comments" New topic
Author

javadoc comments

Chiji Nwankwo
Ranch Hand

Joined: Jun 21, 2002
Posts: 56
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


SCJP, SCJD, SCWCD<br />"Meekness is not weakness, but power under control"
Valentin Crettaz
Gold Digger
Sheriff

Joined: Aug 26, 2001
Posts: 7610
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.


SCJP 5, SCJD, SCBCD, SCWCD, SCDJWS, IBM XML
[Blog] [Blogroll] [My Reviews] My Linked In
Chiji Nwankwo
Ranch Hand

Joined: Jun 21, 2002
Posts: 56
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

Joined: Aug 26, 2001
Posts: 7610
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

Joined: Jun 21, 2002
Posts: 56
thanks
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: javadoc comments