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 Using @see in JavaDoc with respect to Data class and DBAccess interface Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Using @see in JavaDoc with respect to Data class and DBAccess interface" Watch "Using @see in JavaDoc with respect to Data class and DBAccess interface" New topic
Author

Using @see in JavaDoc with respect to Data class and DBAccess interface

Jethro Borsje
Ranch Hand

Joined: Jul 22, 2008
Posts: 100
Hi everybody,

A few weeks back I passed my SCJP exam with a score of 95% and I decided to go right ahead and start working on the SCJD exam. I am wondering how I should use the JavaDoc in the Data class and DBAccess interface. The DBAcces inteface was provided to me by Sun in my assignment (B&S) and I have added JavaDoc to it. My Data class has to implement this interface. Should I copy / paste all this JavaDoc to my Data class for the implemented methods, or can I just say something like "@see suncertify.db.DBAccess#lockRecord(long)"?

Best regards,
Jethro


SCJP, SCJD
satishkumar janakiraman
Ranch Hand

Joined: May 03, 2004
Posts: 334
Hi Jethro,

I have also started reading the requirement of B&S. As per my understanding of the requirement document, we have to provide the java doc comments for our Data class which implements DBAccess interface. The DBAccess interface should not be modified. Write @see tag in your Data class and give a link to DBAccess.

all the best
sat
Jethro Borsje
Ranch Hand

Joined: Jul 22, 2008
Posts: 100
I have modified the DBAccess interface only with respect to the JavaDoc, because it does not contain any JavaDoc if you copy / past it from the assignment. Do you think this modification is allowed?
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2267
    
    3

Hey, partner.

Yes, that modification is totally allowed. You only can't modify the interface itself. But the comments, yes, you can modify them. I myself didn't modify them, I just added the necessary tags on each method (@param, @return, etc).

You do this for the interface, and you don't need to use the @see tag for the implementation, at least not for that purpose. You can use the @see tag to indicate classes/methods that have something to with the method you are currently writing. You can use the @inheritDoc for the implementation, then when you run the javadoc tool, it will use the same description of the method being referenced. For instance:



Cheers, Bob "John Lennon" Perillo
SCJP, SCWCD, SCJD, SCBCD - Daileon: A Tool for Enabling Domain Annotations
satishkumar janakiraman
Ranch Hand

Joined: May 03, 2004
Posts: 334
It is always better to write a java doc comment in your implementation class instead of modifying the existing class/interface.

sat
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2267
    
    3

Howdy, y'all.

Please take a look at this discussion and see what was the answer chosen as the correct one.
Jethro Borsje
Ranch Hand

Joined: Jul 22, 2008
Posts: 100
Thanks for the replies, {@inheritDoc} seems to be the best solution here.
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: Using @see in JavaDoc with respect to Data class and DBAccess interface