This week's book giveaway is in the Kotlin forum.
We're giving away four copies of Kotlin for Android App Development and have Peter Sommerhoff on-line!
See this thread for details.
Win a copy of Kotlin for Android App Development this week in the Kotlin forum!
  • 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 all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Devaka Cooray
  • Jeanne Boyarsky
  • Bear Bibeault
Sheriffs:
  • Junilu Lacar
  • Paul Clapham
  • Knute Snortum
Saloon Keepers:
  • Ron McLeod
  • Tim Moores
  • Stephan van Hulst
  • salvin francis
  • Carey Brown
Bartenders:
  • Tim Holloway
  • Frits Walraven
  • Ganesh Patekar

Question about javadoc  RSS feed

 
Greenhorn
Posts: 21
  • 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?
 
Sheriff
Posts: 11338
178
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • 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
  • 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: 11338
178
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • 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
  • 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.
 
All of the world's problems can be solved in a garden - Geoff Lawton. Tiny ad:
RavenDB is an Open Source NoSQL Database that’s fully transactional (ACID) across your database
https://coderanch.com/t/704633/RavenDB-Open-Source-NoSQL-Database
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!