Win a copy of Functional Reactive Programming this week in the Other Languages forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

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

 
Jethro Borsje
Ranch Hand
Posts: 100
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
satishkumar janakiraman
Ranch Hand
Posts: 334
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 100
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2271
3
Eclipse IDE Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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:

 
satishkumar janakiraman
Ranch Hand
Posts: 334
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2271
3
Eclipse IDE Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 100
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks for the replies, {@inheritDoc} seems to be the best solution here.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic