JDK-4320557 : Doclet API: Automatically add values of static fields to generated docs
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.0,1.2.2
  • Priority: P3
  • Status: Closed
  • Resolution: Duplicate
  • OS: generic,solaris_2.6
  • CPU: generic,sparc
  • Submitted: 2000-03-10
  • Updated: 2014-05-05
  • Resolved: 2001-08-07
Related Reports
Duplicate :  
Duplicate :  
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
11-06-2004

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
07-08-2001