• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Question about javadoc

 
Greenhorn
Posts: 21
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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?
 
Sheriff
Posts: 11604
178
Hibernate jQuery Eclipse IDE Spring MySQL Database AngularJS Tomcat Server Chrome Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 11604
178
Hibernate jQuery Eclipse IDE Spring MySQL Database AngularJS Tomcat Server Chrome Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Nevermind, I was looking at the wrong file. The provided interface doesn't have javadoc.
reply
    Bookmark Topic Watch Topic
  • New Topic