File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes JavaDoc DB Interface & DuplicateKeyException Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of OCA/OCP Java SE 7 Programmer I & II Study Guide this week in the OCPJP forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "JavaDoc DB Interface & DuplicateKeyException" Watch "JavaDoc DB Interface & DuplicateKeyException" New topic
Author

JavaDoc DB Interface & DuplicateKeyException

Sean Keane
Ranch Hand

Joined: Nov 03, 2010
Posts: 581

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?

SCJP (1.4 | 5.0), OCJP (6.0), OCMJD
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5449
    
  13

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.


SCJA, SCJP (1.4 | 5.0 | 6.0), SCJD
http://www.javaroe.be/
Sean Keane
Ranch Hand

Joined: Nov 03, 2010
Posts: 581

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
Bartender

Joined: Jul 19, 2004
Posts: 5449
    
  13

Sean Keane wrote:so that just leaves documenting at the class level comment.

That's indeed a possibility.
Ryan Small
Greenhorn

Joined: Jun 09, 2011
Posts: 3

You can always override the inherited documentation. For instance:



This would override the documentation for just the DuplicateKeyException.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: JavaDoc DB Interface & DuplicateKeyException