It might occur to me to look at valueOf(Class, String) if I was
looking for a method to convert a string to an enum constant, but I
don't think it would occur to me to look there if I was looking for a
method to get all the values of an enum. I'm sure plenty of people end
up using MyEnum.class.getEnumConstants() because that *is* linked to
from the class javadoc. Perhaps a {@link} from the class javadoc to
the valueOf(Class, String) method would be sufficient, like this:
* More information about enums, including descriptions of the
* implicitly declared methods synthesized by the compiler, can be
* found in section 8.9 of
* <cite>The Java™ Language Specification</cite>. See also
* the description in {@link #valueOf valueOf}.
Additionally, Class.getEnumConstants() could mention the simpler
alternative if the class is known at compile time.
Éamonn
2013/8/20 Jonathan Gibbons <jonathan.gibb...@oracle.com>:
> Eamonn,
>
> See
> http://docs.oracle.com/javase/7/docs/api/java/lang/Enum.html#valueOf(java.lang.Class,%20java.lang.String)
>
>
>> Note that for a particular enum type T, the implicitly declared public
>> static T valueOf(String) method on that enum may be used instead of this
>> method to map from a name to the corresponding enum constant. All the
>> constants of an enum type can be obtained by calling the implicit public
>> static T[] values() method of that type.
>
>
> -- Jon
>
> On 08/20/2013 11:00 AM, Eamonn McManus wrote:
>>
>> As I mentioned earlier in the thread, it's kind of user-hostile for
>> the Enum javadoc to send the user to the JLS instead of just saying,
>> even briefly, what the methods are. Even more so since it doesn't
>> actually link to the relevant section of the JLS or in fact to the JLS
>> at all. This is not a complaint that the information isn't documented,
>> just that it is too hard to find. Imagine how much work I have to do
>> if I can't remember the name of the method to convert from a string to
>> an enum constant in a new enum I'm writing, and it doesn't occur to me
>> to pick some other random enum and look at its javadoc.
>>
>> Éamonn
>>
>>
>> 2013/8/20 Jonathan Gibbons <jonathan.gibb...@oracle.com>:
>>>
>>> Paul,
>>>
>>> Enums are well covered in JLS 7, section 8.9. In particular, see 8.9.2,
>>> Enum
>>> Body Declarations, beginning at the line
>>>
>>> "In addition, if E is the name of an enum type, then that type has the
>>> following implicitly declared static methods:"
>>>
>>> -- Jon
>>>
>>>
>>> On 08/20/2013 06:27 AM, Paul Benedict wrote:
>>>>
>>>> Jon, it's not a problem with the method docs, per se. The issue is about
>>>> how the generation isn't documented. My questioning started because I
>>>> was
>>>> using several enums without javadoc available, but I did have the source
>>>> available, and couldn't figure out how the method came to be. Since I've
>>>> asked, everyone knew (but me!) it was a generated method, but I couldn't
>>>> divine that knowledge.
>>>>
>>>> My recommendation is to add an @implNote on Enum.valueOf(Class, String)
>>>> so
>>>> that people know each subclass will get a generated method that behaves
>>>> similarly. What do you think?
>>>>
>>>>
>>>> On Mon, Aug 19, 2013 at 9:23 AM, Paul Benedict <pbened...@apache.org
>>>> <mailto:pbened...@apache.org>> wrote:
>>>>
>>>> I have been working with classes that don't have javadoc
>>>> attachments. The problem was I couldn't find the method in the
>>>> source nor was the method part of the Enum class. So where did it
>>>> materialize from? Now I know the answer: the compiler generates it.
>>>>
>>>> I really think this knowledge should be added to the Enum javadoc
>>>> class. I had to go on quite a goose hunt to find this fact.
>>>>
>>>> Paul
>>>>
>>>>
>>>> On Mon, Aug 19, 2013 at 3:32 AM, Alan Bateman
>>>> <alan.bate...@oracle.com <mailto:alan.bate...@oracle.com>> wrote:
>>>>
>>>> On 18/08/2013 05:07, Paul Benedict wrote:
>>>>
>>>> I think the generated method needs to be listed in the
>>>> class javadoc at
>>>> least. I presume it throws an exception too (like the
>>>> other valueOf) if the
>>>> String can't be resolved to a constant, but no user is
>>>> going to discover
>>>> this fact through the documentation.
>>>>
>>>> Have you checked the generated avadoc for your enum? The
>>>> valueOf(String) should be there and specified to throw IAE or
>>>> NPE.
>>>>
>>>> -Alan
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> -- Cheers,
>>>> Paul
>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Cheers,
>>>> Paul
>>>
>>>
>
