Enum.valueOf(String)

[Eamonn McManus]

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.gibbons at 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.gibbons at 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 <pbenedict at apache.org
>>>> <mailto:pbenedict at 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.Bateman at oracle.com <mailto:Alan.Bateman at 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
>>>
>>>
>