Quick code review request for 634992 (enum) Include links from java.lang.Enum to EnumSet and EnumMap

[Joseph D. Darcy]

Neal Gafter wrote:
> Generally speaking, lower levels in the system shouldn't refer to 
> higher levels.  In this case it's just a comment, but it isn't clear 
> that every profile that includes Enum will include the collections 
> framework.  I'm thinking, for example, about ME profiles.

A few comments on this.

Yes, in general it is true that lower levels shouldn't depend on higher 
levels.  That was the primary reason we decided to have the new 
reflection methods in JDK 5 return arrays rather than generic 
collections.  However, than are many nuances here.

First, there is a difference between an API level dependency, like a 
type used in a signature, and an implementation dependency, something 
that only appears in a method body.  A further distinction is between a 
compile-time implementation dependency and a runtime-only one, such as 
when a class is looked up reflectively.  Additionally, if collections 
and java.lang.Enum are in the same grouping, there is no problem in 
having the dependency.

Second, the underlying model for creating platform javadoc is "compile 
the world" so the presence of absence of particular edges in the 
dependency graph don't really affect what needs to happen.

Finally, the onus for subsetting the API documentation for platform 
subsets ultimately falls on those doing the subsetting.  The javadoc 
build warnings will be there to guide them.

In short, IMO this is an entirely innocuous change that will help those 
learning Java find the enum-optimized set and map implementations.  I 
would even consider adding "Note that when using enums in sets or as 
keys in a map, optimized set and map implementations are available."

Which is probably about an order of magnitude more consideration than 
this change deserves!

-Joe

>
> -Neal
>
> On Fri, Oct 9, 2009 at 4:13 PM, Joe Darcy <Joe.Darcy at sun.com 
> <mailto:Joe.Darcy at sun.com>> wrote:
>
>     Neal Gafter wrote:
>
>         Do EnumSet and EnumMap exist on all platform profiles?
>
>
>     They exist on JDK 7 where this change is intended.
>
>     -Joe
>
>
>         On Fri, Oct 9, 2009 at 11:43 AM, Joseph D. Darcy
>         <Joe.Darcy at sun.com <mailto:Joe.Darcy at sun.com>> wrote:
>
>             Please review this tiny doc fix to make EnumSet and
>             EnumMap just a bit
>             easier to find; patch below
>
>             -Joe
>
>             --- old/src/share/classes/java/lang/Enum.java    2009-10-09
>             11:41:23.000000000 -0700
>             +++ new/src/share/classes/java/lang/Enum.java    2009-10-09
>             11:41:23.000000000 -0700
>             @@ -44,6 +44,8 @@
>              * @author  Josh Bloch
>              * @author  Neal Gafter
>              * @see     Class#getEnumConstants()
>             + * @see     java.util.EnumSet
>             + * @see     java.util.EnumMap
>              * @since   1.5
>              */
>             public abstract class Enum<E extends Enum<E>>
>
>
>
>
>
>