Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Different between interface and implementation classes descriptions in javadoc

 
Mark O' Sullivan
Ranch Hand
Posts: 160
  • Mark post as helpful
  • send pies
  • 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.
 
Roel De Nijs
Sheriff
Posts: 10662
144
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • 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: 10662
144
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • 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
  • 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: 10662
144
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • 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
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic