Propagating JavaDoc

R

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
 
D

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.
 
R

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
 
R

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
 
T

Tim Tyler

Roedy Green said:
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.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,906
Latest member
SkinfixSkintag

Latest Threads

Top