JDK-8167967 : javadoc should identify the ordinal value of enum constants
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 9
  • Priority: P2
  • Status: Closed
  • Resolution: Fixed
  • Submitted: 2016-10-13
  • Updated: 2017-08-08
  • Resolved: 2016-11-15
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.
JDK 9
9 b145Fixed
Related Reports
Blocks :  
JDK-8167441 - j.i.ObjectInputFilter.Status enum values order
Duplicate :  
JDK-8167441 - j.i.ObjectInputFilter.Status enum values order
Relates :  
JDK-8151146 - The order of enum constants is different from the previous version
Description
As a minor presentation issue, the items in the "Enum ConstantsDetail" table for an enum should be in declaration order, not alphabetical order.

More significantly, each entry in the table should specify the ordinal value of the enum.

One way to do this would be to include a one-line paragraph
"Ordinal: N"
either after the signature or after the description (if any).
Comments
The underlying goal here was to identify the ordinal numbers for enum constants. Relying on the (unspecified) ordering characteristics is (at best) a second-best solution. As indicated in the description, a better solution would be to explicitly include the ordinal number somewhere in the generated docs. It's annoying to have to give undue prominence to a feature that is not encouraged, but that would be the best solution. I note the changeset provides the new getOrdinalValue method, but the doclet does not (yet) use it.
11-01-2017
I see. Got your point. Thank you.
11-01-2017
The issue is one of stylistic consistency across *all* summary tables (methods, fields, etc as well as enum members.) Summary tables are sorted alphabetically. Detail tables are presented in declaration order.
10-01-2017
What is the rationale behind not changing the order in the summary ? Please help me understanding that. For the values(), it says :- "an array containing the constants of this enum type, in the order they are declared" There are two places where I can see the order :- Enum Constant Summary and Enum Constant Detail I believe at both the place, the order should be the order of declaration. Am I missing something ?
10-01-2017
The presentation order of fields has changed as well. We should generally check the order of all items between JDK 8 and JDK 9. For example, using series of declarations like these that have an "obvious" non-alphabetic order that is easily checked, at least visually: In "Summary" tables, the order should be alphabetic; in "Detail" tables, the order should be natural (i.e. declaration order, for decls in source files.) public interface Intf { void one(); void two(); void three(); void four(); } public class Class { public int one; public int two; public int three; public int four; } public enum E { ONE, TWO, THREE, FOUR } public @interface Anno { one(); two(); three(); four(); } etc
14-10-2016