Win a copy of Clojure in Action this week in the Clojure forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Question about javadoc

 
Björn Wessman
Greenhorn
Posts: 21
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Sheriff
Posts: 9157
76
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Björn Wessman
Greenhorn
Posts: 21
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Sheriff
Posts: 9157
76
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 21
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Nevermind, I was looking at the wrong file. The provided interface doesn't have javadoc.
 
I agree. Here's the link: http://aspose.com/file-tools
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic