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

Question about javadoc

Björn Wessman
Greenhorn

Joined: Jun 01, 2009
Posts: 21
Hello!

If I have methods defined in an interface, should I write functionality detailed information in the java doc in the interface? For example, in my implementation method for find(), I filter out all records I got from my data search that didn't EXACTLY match the criteria. I explain that in the javadoc for the implementer class, but should I do it in the interface as well? It would be useful to have that info right from the top of the hierarchy, but at the same time, that functionality isn't defined until it's actually implemented, and the implementation could change...

How would you guys do?
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5597
    
  15

Hi Bjorn,

If I get your interface to reimplement it I have to know what the contract of the method is. So if that method should only return records exactly matching some criteria you have to put it in the javadoc interface. Because that method will be invoked from the GUI and user will see only the matching records. But if you didn't mention it, I would not know of this behavior, so I don't filter records in the reimplementation and user will see a lot more records in the GUI (not exactly matching his search criteria).

From my find-method:


Kind regards,
Roel


SCJA, SCJP (1.4 | 5.0 | 6.0), SCJD
http://www.javaroe.be/
Björn Wessman
Greenhorn

Joined: Jun 01, 2009
Posts: 21
OK, thanks for the advice. A follow-up question: would you use @inheritDoc or copy-paste the javadoc if they are exactly the same in the interface as in the implementer class?
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5597
    
  15

Hi Bjorn,

I used the @inheritDoc, because it's easy and you are certain that both comments are exactly the same. If you copy/paste and afterwards do a small change, you might forget changing it in the class too

Regards,
Roel
Björn Wessman
Greenhorn

Joined: Jun 01, 2009
Posts: 21
Nevermind, I was looking at the wrong file. The provided interface doesn't have javadoc.
 
Don't get me started about those stupid light bulbs.
 
subject: Question about javadoc