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 Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Spring in Action this week in the Spring forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "javadoc" Watch "javadoc" New topic
Author

javadoc

Torsten Wiederkehr
Greenhorn

Joined: Feb 20, 2004
Posts: 14
Hi @all,

I have two questions about documentation in javadoc.

1.) Do I have to document private instance variables?

2.) Do I have to document methods, which are alread documented in an interface? Or is it enought to use the @see Tag to reference to the interface?


ciao torsten
mike acre
Ranch Hand

Joined: Sep 23, 2003
Posts: 197
Obviously you need to comment all class members, but javadoc is only required for the public interface - personally I javadoced everything except private.

For inheritence use the {@inheritDoc} tag (rather than @see) for body and all applicable exceptions wherever possible - you should write the comments that are inherited in such away as they will apply to all inheritees ie don't mention implementation details in interface comments. You can always add to the above tag with specific implementation details.

Read the javadoc tool docs carefully for this tags useage.

Note the {@inheritTag} is a bit bugtastic at present


SCJP 1.4, SCJD
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11476
    
  94

Hi Torsten & Mike,

Also note that the interface does not have javadoc comments when you get it - so if you are going to inherit the comments, you will need to fix this .

Regards, Andrew


The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
Torsten Wiederkehr
Greenhorn

Joined: Feb 20, 2004
Posts: 14
Hi,

I use {@inheritDoc} instead of @see now, but I get the following waring for classes which implement an interface and this interface extends another interface before.

IDataBaseAccess
|
|
IDataBaseAccessRemote
|
|
DataBaseAccessRMI

DataBaseAccessRMI.java:132: warning - @inheritDoc used but delete(int) does not override or implement any method.

Should I stick to the {@inheritDoc} tag or should I use the @see tag here, to avoid the warning.


ciao torsten
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: javadoc