United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4320557 : Doclet API: Automatically add values of static fields to generated docs

Details
Type:
Enhancement
Submit Date:
2000-03-10
Status:
Closed
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2001-08-07
Component:
tools
OS:
solaris_2.6,generic
Sub-Component:
javadoc(tool)
CPU:
sparc,generic
Priority:
P3
Resolution:
Duplicate
Affected Versions:
1.2.0,1.2.2
Fixed Versions:

Related Reports
Duplicate:
Duplicate:

Sub Tasks

Description
The values of static final fields must be specified in the API specification. 
Until now we have relied on developers writing in the values by hand in the 
body of the doc comments, which very few do.

More technically, we would publish the value for: (according to Josh)

  All primitive and String final static fields that are 
  initialized to compile-time constant expressions. 

To ensure that this be done accurately, Javadoc should automate this,
inserting the value in the generated output.

This needs to be done for both the standard and MIF doclets.

Note that the implementation should be sure to specify the values for 
private and package-private static final fields in those cases when the 
user supplies the -private or -package flags to javadoc.  

Once this is done, we should create a doc bug report to remove the
manually-added values from the comment bodies.

If the value is added to the signature, it may be necessary to modify the
localization pre-process doclet to strip off the value, because the
signature is used as a key in the comment (.cmnt) file to uniquely
identify the comment.

                                    

Comments
SUGGESTED FIX

Josh proposes adding an equal sign (=) with the value after the signature
in the field "detail" section. (Value would not appear in the summary section)

In class java.lang.Integer:
--------------------------------------------------
MAX_VALUE

public static final int MAX_VALUE = 2147483647
                                  ^^^^^^^^^^^^
      The largest value of type int. 
--------------------------------------------------

Note that this requires someone manually going in and removing 
the sentence "The constant value of this field is 2147483647."

Source: 
http://java.sun.com/j2se/1.3/docs/api/java/lang/Integer.html#MAX_VALUE
                                     
2004-06-11
EVALUATION

Necessary for debugging (by developers), compatible implementations (by licensees), and compliance testing (by Java Compatibility Tests).

It appears this requires an addition to the Doclet API to get the field value.
doug.kramer@Eng 2000-09-06

Re-opening the bug marked INT, as verification fails. Followed is the correspondence I had with the developer.

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Vijayan R A wrote:
> I am in the process of verifying the fix/Integration. I wrote a simple test
> case,
> 
> jtools-sqe:/vijayan/newchild/regression/T4320557 120 % more Test.java
> /**
>  * Class Test
>  */
> public class Test
> {
>         public  static final int        fIntField = 1;
> }

Your test is correct, but 4478115 is preventing this from working properly yet.
That bug should probably not have been marked fixed/integrated yet.

-Neal
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

vijayan.ra@India 2001-08-07

I am closing this, as the standard doclet work is completed and 4478115 remains
open to track the remaining problem.

neal.gafter@Eng 2001-08-07
                                     
2001-08-07



Hardware and Software, Engineered to Work Together