JDK-5009943 : Javadoc generated for enums could be misleading
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 5.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2004-03-09
  • Updated: 2014-05-05
  • Resolved: 2004-04-26
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
5.0 b49Fixed
Related Reports
Duplicate :  
Relates :  
Relates :  
###@###.### 2004-03-08

J2SE Version (please include all output from java -version flag):
  java version "1.5.0-beta2"
  Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-beta2-b40)
  Java HotSpot(TM) Client VM (build 1.5.0-beta2-b40, mixed mode)

Does this problem occur on J2SE 1.3.x or 1.4.x?  Yes / No (pick one)

Bug Description:

The Javadoc standard doclet generates documentation which, for classes 
and interfaces, includes something which looks like a fragment of a type 
declaration equivalent to that used in the actual source code :

    public final class String
    extends Object
    implements Serializable, Comparable<String>, CharSequence

In particular, it is a fragment of legal Java code which, with the 
addition of some imports and an appropriate body, could compile to the 
type documented.  However this is not the case for enums, which are 
displayed as:

    public static enum RoundingMode
    extends Enum<RoundingMode>

Given that enums are a new language feature with certain unique rules 
regarding modifiers and inheritance, displaying an illegal fragment of 
something which looks like the enum's declaration could cause confusion 
as to what is and is not allowed when declaring enums.  For example, it 
could be inferred (consciously or otherwise) from reading this that :

1) The static modifier is permitted on top level enum declarations
2) Distinct concepts of static and non-static enums exist and are 
available to the programmer via the inclusion or omission of the static 
3) The extends clause is permitted on enum declarations
4) The exact type which the enum extends may be specified by the programmer

None of which are true to the best of my knowledge.  Therefore I suggest 
that the standard doclet be changed such that:

1) The static modifier is not shown, at least for top level enums.
2) If RFE 5009540 is implemented as suggested, the extends clause should 
be omitted also, as this information would be present in the class 
hierarchy displayed at the top of the same page.

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger-beta2 FIXED IN: tiger-beta2 INTEGRATED IN: tiger-b49 tiger-beta2

EVALUATION ###@###.### wrote: - Low Risk. The doclet already has code to omit keywords that are unnecessary. We simply have to add "final" to the list of keywords to omit from the output. - Approx. 3 to 5 lines of code to change - The modifier is keyword "noise" that should be surpressed. There is really no need for it. We should remove it to have cleaner output. ###@###.### 2004-04-12 Fixed. ###@###.### 2004-04-20

PUBLIC COMMENTS The static modifier has been removed as a side affect of the fix for 5010455. However, the final modifier now appears. The doclet should omit this. ###@###.### 2004-04-01 The final modifier is now omitted from the output. ###@###.### 2004-04-20