Propagating JavaDoc

[Roedy Green]

I wondered what is considered the best practice to handle the
following situations.

What should the java doc look like on:

1. a static method or constant that is implemented all over the place.

2. a method that appears all over the place in different classes, all
overriding the base method.


What technique do you use to propagate whatever Javadoc you feel is
appropriate, and how do you keep it current?


--
Bush crime family lost/embezzled $3 trillion from Pentagon.
Complicit Bush-friendly media keeps mum. Rumsfeld confesses on video.
http://www.infowars.com/articles/us/mckinney_grills_rumsfeld.htm

Canadian Mind Products, Roedy Green.
See http://mindprod.com/iraq.html photos of Bush's war crimes

 

[Daniel Dyer]

I wondered what is considered the best practice to handle the
following situations.

What should the java doc look like on:

1. a static method or constant that is implemented all over the place.

2. a method that appears all over the place in different classes, all
overriding the base method.


What technique do you use to propagate whatever Javadoc you feel is
appropriate, and how do you keep it current?

Not sure what you mean for 1, but for 2 comments can be inherited:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

Dan.

 

[Roedy Green]

Not sure what you mean for 1, but for 2 comments can be inherited:

e.g.

/**
* Version number for this class used in serialisation.
*/
public static final long serialVersionUID = 19L;

or

/**
* Used by getSchoolColours.
* The colours for this School class implementation
*/
private static final Color[] schoolColours = { Color.red, Color.black,
Color.yellow };

This comment appears in many places.

--
Bush crime family lost/embezzled $3 trillion from Pentagon.
Complicit Bush-friendly media keeps mum. Rumsfeld confesses on video.
http://www.infowars.com/articles/us/mckinney_grills_rumsfeld.htm

Canadian Mind Products, Roedy Green.
See http://mindprod.com/iraq.html photos of Bush's war crimes

 

[Roedy Green]

Not sure what you mean for 1, but for 2 comments can be inherited:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

that's good. I like the idea of an explicit marker.

@param {@inheritDoc}

Presumably you can use to it inherit the base doc and add to it.

--
Bush crime family lost/embezzled $3 trillion from Pentagon.
Complicit Bush-friendly media keeps mum. Rumsfeld confesses on video.
http://www.infowars.com/articles/us/mckinney_grills_rumsfeld.htm

Canadian Mind Products, Roedy Green.
See http://mindprod.com/iraq.html photos of Bush's war crimes

 

[Tim Tyler]

What technique do you use to propagate whatever Javadoc you feel is
appropriate, and how do you keep it current?

I tend not to use Javadoc when writing applications - it's far too
much of a maintenance headache.

It's better to have self-documenting code - and reserve comments for
the occasions when you want to say things like what needs to be done.