File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes javadoc for implementing public methods 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 for implementing public methods" Watch "javadoc for implementing public methods" New topic

javadoc for implementing public methods

Dieskun Koper
Ranch Hand

Joined: Aug 15, 2004
Posts: 85

I am wondering how to document methods that implement methods defined (and documented with javadoc) in interfaces.
For example:

public interface DBMain {
* Searches blah blah
* @tag blah
public search();

How should I document my implementing class?

public class Data {
* [ copy and paste from interface ?? ]
public search() {

Copying and pasting sounds like a maintenance horror.
If I do not write any comment for the implementing method, javadoc will copy the documentation from the interface. But my spec says:
"javadoc style comments must be used for each element of the public interface of each class"
I assume "each element of the public interface of each class" means each public method, so I am considering copying and pasting the comments.

I'd like to hear your opinions..

Mark Spritzler

Joined: Feb 05, 2001
Posts: 17276

You interface should have the Javadoc, the implementing class does not need to javadoc, since it is already in the interface.


Perfect World Programming, LLC - iOS Apps
How to Ask Questions the Smart Way FAQ
Dieskun Koper
Ranch Hand

Joined: Aug 15, 2004
Posts: 85
I noticed with javadoc, when you do not write any javadoc for a public method, it sometimes copies it from the interface with a comment as follows:
Description copied from interface: xxx
However, it only seems to do that for the first interface in the implements clause.
For instance, I have a table model extending AbstractTableModel, and it will not generate javadoc for methods like getColumnCount unless I explicitely add 'implements TableModel' to my class definition.
I wonder why that is.
Raj Nagappan
Ranch Hand

Joined: May 26, 2004
Posts: 38
You can use @inheritDoc to force a method to repeat the javadoc from its interface or superclass. Very effective.


Raj Nagappan<br />SCJP, SCJD, PhD
Dieskun Koper
Ranch Hand

Joined: Aug 15, 2004
Posts: 85
Thanks Raj.
I already submitted my assignment, but I'll have a look at it anyway.
I was thinking of reading the javadoc manual, also when I got a warning for all the <br>'s I used, but somehow I forgot.
I agree. Here's the link:
subject: javadoc for implementing public methods
It's not a secret anymore!