• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

JavaDoc DB Interface & DuplicateKeyException

 
Sean Keane
Ranch Hand
Posts: 582
Chrome Eclipse IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
From a quick search of the forum I gather that many people have added JavaDoc comments directly to the interface provided by Oracle - but they kept the description text in the JavaDoc precisely the same as the original comments provided by Oracle. So I am guessing this is an OK approach to use?

Following on from this, for people who took this approach, what did you document for the DuplicateKeyException in the create method?

I think most people simply ignore this exception i.e. they never throw it in their implementation. So what would be an appropriate JavaDoc comment for the interface?

Anyone who took this approach of adding JavaDoc to the interface did you then add {@inheritDoc} to ALL of the methods in your Data class that implemented the interface methods? If so, how did you comment the DuplicateKeyException in the interface class in such a way that it wouldn't be confusing when reading the JavaDoc of your Data class?

For example, if you documented it as follows:

Then how would I know when reading the inherited JavaDoc from the Data class that there are no key constraints? I could add a comment to overall JavaDoc comment for the Data class that there are no key constraints in this implementation - what did you guys do?
 
Roel De Nijs
Sheriff
Posts: 10238
129
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Sean Keane wrote:Anyone who took this approach of adding JavaDoc to the interface did you then add {@inheritDoc} to ALL of the methods in your Data class that implemented the interface methods?

That's what I did.

Sean Keane wrote:Then how would I know when reading the inherited JavaDoc from the Data class that there are no key constraints?

Why would you need to know that? The Data class implements the given interface, so you know it meets the requirements defined in the contract (the given interface). If the exception is actually thrown from the create-method is not important, the only thing that is important: if a duplicate key is encountered when creating a new record, a DuplicateKeyException is thrown.
 
Sean Keane
Ranch Hand
Posts: 582
Chrome Eclipse IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Roel De Nijs wrote:
Sean Keane wrote:Then how would I know when reading the inherited JavaDoc from the Data class that there are no key constraints?

Why would you need to know that?


When I am reading the JavaDoc of the Data class and I see that it's possible that an exception could be thrown when creating a record due to a duplicate key, then I want to know what the constraints on the key are. But there are no constraints on the key in this implementation - so of course this is something you should document somewhere.

If I use the {@inheritDoc} then I can't document at the method level, so that just leaves documenting at the class level comment.
 
Roel De Nijs
Sheriff
Posts: 10238
129
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Sean Keane wrote:so that just leaves documenting at the class level comment.

That's indeed a possibility.
 
Ryan Small
Greenhorn
Posts: 3
Eclipse IDE Java Netbeans IDE
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You can always override the inherited documentation. For instance:



This would override the documentation for just the DuplicateKeyException.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic