• 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

Different between interface and implementation classes descriptions in javadoc

 
Ranch Hand
Posts: 160
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi,
Just wondering are the Javadoc descriptions for both interfaces and their implementing classes much the same, would they both contain:
(1) description of method
(2) description of parameters passed
(3) description of both checked and Runtime exceptions.
The reason I'm asking is because in my implementation classes I have used some <code></code> inline tags to associate with implementation details and these need not be known in the interface. Does one just leave this information out in the interface descriptions?
Thanks.
 
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 Mark,

The javadoc comment for the read-method in my interface is like this:


The javadoc comment for the read-method in the class implementing my interface is like this:


Nice and easy!

Kind regards,
Roel
 
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 Mark,

And as a final remark I want to add the following. In one of my methods I pass a parameter of type Object, because the actual value will be dependent on the specific implementation (and because your interface should mention no implementation details, the parameter has to be of type Object).

So in my javadoc comment of this method I have something like:


And in my implementation class I just used the {@inheritDoc} tag as described in my previous post. But I added a comment in my class level javadoc comments about what is expected to be passed on to that method: "the doCoolThings-method expects a String with the password to login on the server".

Kind regards,
Roel
 
Mark O' Sullivan
Ranch Hand
Posts: 160
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi,
Thanks for your reply. That makes things clearer. I also want to list the runtimeException's somewhere in the Javadoc description and wondering is this placed in the interface or the implementing class or both? My confusion lies in the fact that a business could give a developer the required interface to implement, therefore the runTimeException's would not need to be specified but when a developer is published his code, can he modify the interface to include these runtimeexception's or are these descripted in the Javadoc comments in the implementing class?
Thanks very much!
 
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 Mark,

What RuntimeExceptions are you talking about?

All methods of the data-interface (interface implemented by Data class) have "throws IllegalArgumentException" and/or "throws IllegalStateException" when appropriate. The methods in the implementation class (the Data class) just use the {@inheritDoc} tag.

And the same rule applies to my BusinessService and the implementation classes.

Kind regards,
Roel
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
reply
    Bookmark Topic Watch Topic
  • New Topic