• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

javadoc

 
Greenhorn
Posts: 14
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 197
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
author and jackaroo
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
reply
    Bookmark Topic Watch Topic
  • New Topic