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