Well, I presume other learning materials for Java (tutorials, ... for
dummies, etc) will explain the existence of these methods as part of the
language feature that is "enum"s.
Quite where the bytecodes for the methods comes from is implementation
detail that should not need to be documented in end-user docs.
Interestingly, though, is that the javadoc for Enum.valueOf *does* have
something close to the text you want:
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 07:29 AM, Paul Benedict wrote:
So are you recommending not to alter the Javadoc of Enum to mention
this fact? Going to the JLS is great for compiler developers, but it's
not the first place for the end user.
On Tue, Aug 20, 2013 at 8:48 AM, Jonathan Gibbons
<jonathan.gibb...@oracle.com <mailto:jonathan.gibb...@oracle.com>> wrote:
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
--
Cheers,
Paul
