Enum.values( ) API Documentation
Marc van Dongen
I know what the class method values( ) of enum classes is for, but
don't seem to
be able to find the API in the API documentation on
http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Enum.html,
I'd appreciate it if somebody could let me know where to find it.
Thanks in advance for your help.
Regards,
Marc van Dongen
Peter Duniho
> Howsagoin,
>
>
> I know what the class method values( ) of enum classes is for, but
> don't seem to
> be able to find the API in the API documentation on
> http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Enum.html,
>
> I'd appreciate it if somebody could let me know where to find it.
You should be looking in the latest version documentation (i.e. Java 6:
http://java.sun.com/javase/6/docs/api/java/lang/Enum.html).
But, that particular method is, as I understand it, automatically
generated by the compiler. It won't show up in the API documentation,
as it's not actually part of the java.lang.Enum type itself, but rather
something that shows up in each actual declared enum automatically.
You can probably find details in the Java specification.
Pete
Patricia Shanahan
markspace
> You can probably find details in the Java specification.
Yup, you can find it in section 8.9 of the JLS:
<http://java.sun.com/docs/books/jls/third_edition/html/classes.html#8.9>
"In addition, if E is the name of an enum type, then that type has the
following implicitly declared static methods:
/**
* Returns an array containing the constants of this enum
* type, in the order they're declared. This method may be
* used to iterate over the constants as follows:
*
* for(E c : E.values())
* System.out.println(c);
*
* @return an array containing the constants of this enum
* type, in the order they're declared
*/
public static E[] values();
/**
* Returns the enum constant of this type with the specified
* name.
* The string must match exactly an identifier used to declare
* an enum constant in this type. (Extraneous whitespace
* characters are not permitted.)
*
* @return the enum constant with the specified name
* @throws IllegalArgumentException if this enum type has no
* constant with the specified name
*/
public static E valueOf(String name);
"
In my opinion, the Java doc is defective for not mentioning these
methods. It should copy-and-paste the above section into the Java doc
for the Enum class, so that the information is ready-to-hand for anyone
looking at the Enum methods.
Peter Duniho
> [...]
> In my opinion, the Java doc is defective for not mentioning these
> methods. It should copy-and-paste the above section into the Java doc
> for the Enum class, so that the information is ready-to-hand for anyone
> looking at the Enum methods.
I agree, sort of.
I understand the reasoning behind not including those methods in the
class documentation proper. They _aren't_ part of the java.lang.Enum
type, and it would be inconsistent for the docs to pretend that they are.
However, the remarks section for the java.lang.Enum type itself is
incredibly sparse, providing no guidance whatsoever on the proper usage,
common patterns, etc. of enums. It should provide those details, and in
those details, it would specifically mention the values() and valueOf()
method that are generated by the compiler in concrete enum types.
I don't think that the methods should in fact appear in the list of
methods for the java.lang.Enum class, but yes�definitely, the
documentation should discuss them _somewhere_.
Pete
markspace
> I don't think that the methods should in fact appear in the list of
> methods for the java.lang.Enum class, but yes�definitely, the
> documentation should discuss them _somewhere_.
I agree not with the list of methods; those two methods aren't members
of Enum class and it would be really confusing to add them there.
As I said, that section of the JLS should be copied into the class
documentation, which is to say the blob of text that precedes the list
of methods. They could just cut-and-paste the same section that I did
and it would be perfectly readable.
Marc van Dongen
> Marc van Dongen wrote:
> > Howsagoin,
>
[ snip ]
> You should be looking in the latest version documentation (i.e. Java 6:http://java.sun.com/javase/6/docs/api/java/lang/Enum.html).
>
> But, that particular method is, as I understand it, automatically
> generated by the compiler. It won't show up in the API documentation,
> as it's not actually part of the java.lang.Enum type itself, but rather
> something that shows up in each actual declared enum automatically.
>
> You can probably find details in the Java specification.
Thanks. I am aware that this method is generated and I know what it
does.
Still I think it makes sense to include the method in the API docs. A
programmer of the java language should be able to find the method's
documentation without any knowledge about the java implementation.
Regards,
Marc van Dongen
Marc van Dongen
> Yup, you can find it in section 8.9 of the JLS:
>
> <http://java.sun.com/docs/books/jls/third_edition/html/classes.html#8.9>
[ snip ]
> public static E[] values();
Thanks. I've googled around a bit and this is the first time I see
an explicit type signature for the method. All other references to
the method describe the method in words.
Thanks again.
Regards,
Marc van Dongen
Peter Duniho
> [...]
> Still I think it makes sense to include the method in the API docs. A
> programmer of the java language should be able to find the method's
> documentation without any knowledge about the java implementation.
As you can see my discussion with "markspace", I agree it should be
documented in the remarks for the java.lang.Enum class. However, it's
also true that a programmer of the Java language should be familiar
with, and be comfortable reviewing, the Java Language Specification.
If you think of the JLS as "implementation" (I don't, but that's a
separate matter), then it's not true you should be able to write Java
code without any knowledge of the JLS. Whether you read the JLS itself,
or just learn about it through other documentation, you _must_ have
knowledge of the JLS. It's not possible to write Java code otherwise.
Pete
Lew
>> Yup, you can find it in section 8.9 of the JLS:
>>
>> <http://java.sun.com/docs/books/jls/third_edition/html/classes.html#8.9>
>
> [ snip ]
>
>> public static E[] values();
Marc van Dongen wrote:
> Thanks. I've googled around a bit and this is the first time I see
> an explicit type signature for the method. All other references to
> the method describe the method in words.
You should get in the habit of reading the JLS.
--
Lew
Tom Anderson
> In article <alpine.DEB.1.10.1...@urchin.earth.li>,
> Tom Anderson <tw...@urchin.earth.li> wrote:
>
>> On Mon, 22 Feb 2010, markspace wrote:
>>
>>> In my opinion, the Java doc is defective for not mentioning these
>>> methods. It should copy-and-paste the above section into the Java
>>> doc for the Enum class, so that the information is ready-to-hand
>>> for anyone looking at the Enum methods.
>>
>> If you make javadoc for the enum itself, does that include the
>> synthetic methods? That seems like the right place for it to me -
>> Colours.values() is a method of the Colours type, not Enum.
>
> That makes sense, e.g.
>
> <http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html>
> <http://robotchase.sourceforge.net/org/gcs/robot/Key.html>
That's the bunny!
tom
--
an expertly crafted mix of practical decision-making and drunken shouting
Tom Anderson
> In my opinion, the Java doc is defective for not mentioning these
> methods. It should copy-and-paste the above section into the Java doc
> for the Enum class, so that the information is ready-to-hand for anyone
> looking at the Enum methods.
If you make javadoc for the enum itself, does that include the synthetic
methods? That seems like the right place for it to me - Colours.values()
is a method of the Colours type, not Enum.
tom
--
Tristan Tzara offered to create a poem on the spot by pulling words at
random from a hat. A riot ensued and Andre Breton expelled Tzara from
the movement.
John B. Matthews
> On Mon, 22 Feb 2010, markspace wrote:
>
> > In my opinion, the Java doc is defective for not mentioning these
> > methods. It should copy-and-paste the above section into the Java
> > doc for the Enum class, so that the information is ready-to-hand
> > for anyone looking at the Enum methods.
>
> If you make javadoc for the enum itself, does that include the
> synthetic methods? That seems like the right place for it to me -
> Colours.values() is a method of the Colours type, not Enum.
That makes sense, e.g.
<http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html>
<http://robotchase.sourceforge.net/org/gcs/robot/Key.html>
--
John B. Matthews
trashgod at gmail dot com
<http://sites.google.com/site/drjohnbmatthews>
Marc van Dongen
> > If you make javadoc for the enum itself, does that include the
> > synthetic methods? That seems like the right place for it to me -
> > Colours.values() is a method of the Colours type, not Enum.
>
> That makes sense, e.g.
>
> <http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html>
> <http://robotchase.sourceforge.net/org/gcs/robot/Key.html>
Thanks. Good to see it's there.
Regards,
Marc van Dongen
markspace
> On Mon, 22 Feb 2010, markspace wrote:
>
>> In my opinion, the Java doc is defective for not mentioning these
>> methods. It should copy-and-paste the above section into the Java doc
>> for the Enum class, so that the information is ready-to-hand for
>> anyone looking at the Enum methods.
>
> If you make javadoc for the enum itself, does that include the synthetic
> methods? That seems like the right place for it to me - Colours.values()
> is a method of the Colours type, not Enum.
It still should be documented in the super type, imo, since the method
is generated. Is see the distinction, but it would be very convenient
to have it in the Java doc for Enum.
Tom Anderson
I don't disagree. The more ways you can get knowledge in front of people's
eyes, the better.
tom
--
It's not even just bad. It's Waterworld bad, it's Iraq-occupation bad,
it's '62 Mets bad. -- robotslave
Roedy Green
<don...@cs.ucc.ie> wrote, quoted or indirectly quoted someone who said
:
>
>
>I know what the class method values( ) of enum classes is for, but
>don't seem to
>be able to find the API in the API documentation on
>http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Enum.html,
>
>I'd appreciate it if somebody could let me know where to find it.
>
>Thanks in advance for your help.
values() and valueOf(String) are generated methods. You won't find
them in any Sun class to be JavaDoced. They are discussed in the JLS.
I explain how they work at http://mindprod.com/jgloss/enum.html
--
Roedy Green Canadian Mind Products
http://mindprod.com
Imagine an architect who would never admit to making sketches, blueprints or erecting scaffolds. In his view, the finished building speaks for itself. How could a young architect learn from such a man? Mathematicians traditionally refuse ever to disclose the intuitions that lead them to a conjecture, or the empirical tests to see if it were likely true, or the initial proofs. They are like chefs who refuse to disclose their recipes, ingredients or techniques.
Marc van Dongen
wrote:
> values() and valueOf(String) are generated methods. You won't find
> them in any Sun class to be JavaDoced. They are discussed in the JLS.
>
> I explain how they work at http://mindprod.com/jgloss/enum.html
Thanks Roedy, I knew that this method is generated. What I didn't know
was
that documentation was generated for the method in the new enum class.
Thanks to John B. Matthews for providing an example.
Regards,
Marc van Dongen
Patricia Shanahan
Even if the Java developers do not want to maintain the documentation in
two places, the Enum API documentation could be improved by adding a
reference to the relevant section in the JLS.
Patricia
John B. Matthews
Patricia Shanahan <pa...@acm.org> wrote:
Such a reference is not without precedent:
$ find javadoc/jdk6 -name \*html \
| xargs -J % grep "Java Language Specification" % \
| wc -l
159
E.g. <http://java.sun.com/javase/6/docs/api/java/lang/String.html>
Tom Anderson
> Such a reference is not without precedent:
>
> $ find javadoc/jdk6 -name \*html \
> | xargs -J % grep "Java Language Specification" % \
> | wc -l
> 159
Which xargs has a -J? Solaris or something?
tom
--
Hesgadin. It was in two parts - both of them silent. I remember this map
came with a letter accusing me of stealing eggs. I had never understood
the relationship of the map to the accusation. I still don't, but I'm
grateful for the map.
Peter Duniho
> On Wed, 24 Feb 2010, John B. Matthews wrote:
>
>> Such a reference is not without precedent:
>>
>> $ find javadoc/jdk6 -name \*html \
>> | xargs -J % grep "Java Language Specification" % \
>> | wc -l
>> 159
>
> Which xargs has a -J? Solaris or something?
From John's message header:
User-Agent: MT-NewsWatcher/3.5.3b3 (Intel Mac OS X)
And from the Mac OS X xargs man page:
-J replstr
If this option is specified, xargs will use the data read from
standard input to replace the first occurrence of replstr instead
of appending that data after all other arguments. This option
will not affect how many arguments will be read from input (-n),
or the size of the command(s) xargs will generate (-s). The
option just moves where those arguments will be placed in the
command(s) that are executed. The replstr must show up as a dis-
tinct argument to xargs. It will not be recognized if, for
instance, it is in the middle of a quoted string. Furthermore,
only the first occurrence of the replstr will be replaced. For
example, the following command will copy the list of files and
directories which start with an uppercase letter in the current
directory to destdir:
/bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir
Hope that wasn't more info than you were hoping for. Of course, I never
did really answer the precise question you asked. There may be other
platforms with an xargs that has the -J option. But it seems likely
that John's use comes from the same OS he's using to post his message,
Mac OS X. :)
Pete
Tom Anderson
Huh. As a five-year OS X user, not knowing this is quite embarrassing.
It's a nice feature. Thanks for the very sensible find.
I noticed that on linux (and possibly on other unices - not sure if it's a
GNUism or not) several commands (like mv and cp) that are usually of the
form COMMAND INPUT1 INPUT2 ... INPUTN OUTPUT have variant like COMMAND -t
OUTPUT INPUT1 INPUT2 ... INPUTN. I can only assume this is to make them
more xargs-friendly. -J is a better alternative!
> Hope that wasn't more info than you were hoping for.
Never.
> Of course, I never did really answer the precise question you asked.
> There may be other platforms with an xargs that has the -J option.
I suspect BSD. Yup:
> But it seems likely that John's use comes from the same OS he's using to
> post his message, Mac OS X. :)
Indeed, a conclusion of almost Holmesian perspicacity.
tom
--
24-Hour Monkey-Vision!
John B. Matthews
> I suspect BSD.
$ man xargs | head -1 | awk '{ print $1" "$2 }'
XARGS(1) BSD
Alpine on Mac OS X?
<http://www.madboa.com/geek/pine-macosx/>
Also on MacPorts:
<http://trac.macports.org/browser/trunk/dports/mail/alpine/Portfile>