Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

javadoc

 
Torsten Wiederkehr
Greenhorn
Posts: 14
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 197
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12014
220
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Torsten Wiederkehr
Greenhorn
Posts: 14
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic