Hi, this mail is intended as a comment on bug report 4320557 that covers
inclusion of the values of static final fields in javadoc documentation.
(Please, let me know if I have misunderstood the whole idea.)

Problem:
---------------------------------------------------
At a www page (www address and excerpt below) I could read about one of the
new the additions to Javadoc. The addition of value exposal for static
fields. As I could read in the example the value of the static field is now
to be exposed in the documentation. I thought of this previous "value
hiding" to be a very proper and rational decision in favor of object
oriented programming where you are supposed to use a constant to simplify
maintenance and readability.

Problem Example:
---------------------------------------------------
methodCall(MyConstants.CONSTANT);
rather than
methodCall(1);
The latter method call might be the scenario for lazy or new java
programmers using the javadoc as programming reference.

When producing javadocumentation for private use or group/company internal
use I agree that rare cases one might want to be able to see the actual
value (mostly in protected and private constants). But I can hardly see the
point in everyday use with packages from another party. Rather the opposite.
The value hiding helps constant fields values to change over development,
and used correctly they can be changed without notice as as long as other
classes that use that class (or package) are recompiled (no need to change
the code).

I know this is a bit late to hand in suggestions while the bug report
subject is closed but I could not let this pass me by.
I can see a potential hazard here.

Solution Suggestion:
---------------------------------------------------
Let the static final constants whose values are suposed to be shown in the
documentation add a @showvalue parameter in their javadoc comment.
Further more let the javadoc program (or doclet) to use a parameter
-showvalue to tell the documenting program wheather to include the values of
those fields that have a @showvalue attribute in their javadoc comment at
all.

By doing this you let the rare cases where one might want to see the value
in the documentation be visible.
Your code and comments written for java v1.3 is compatible. You can document
the code but if you want to see your values you will have to edit the code
first. A modest effort in most cases.
You can still easily produce valueless documentation for export to other
developers that should not have to bother themselves with the actual values.


Solution Suggestion Example:
---------------------------------------------------
/**
* Value to turn off all sideeffects.
* @showvalue
*/
public static final int NO_OUTPUT = 1;

% javadoc -d /api/ -showvalue MyClass.java


Excerpts from www:
-----------------------------------------------------------------------

http://java.sun.com/j2se/1.4/docs/tooldocs/javadoc/whatsnew-1.4.html

Include values of static field constants - NOT IN BETA 2 - The values of
static field constants now appear in the generated docs. For example, the
value for MAX_VALUE appears as: "public static final int MAX_VALUE =
2147483647" This change required adding to the Doclet API the methods
FieldDoc.constantValue() and FieldDoc.constantValueExpression() in package
com.sun.javadoc. (4320557
<http://developer.java.sun.com/developer/bugParade/bugs/4320557.html&gt;,
4422788)