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