Enum.values( ) API Documentation

[Marc van Dongen]

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.

Thanks in advance for your help.

Regards,


Marc van Dongen

 

[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.

 

[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]

[ 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

 

[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();

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.

 

[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

 

[John B. Matthews]

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>

 

[Tom Anderson]

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

 

[Marc van Dongen]

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]

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]

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.

I don't disagree. The more ways you can get knowledge in front of people's
eyes, the better.

tom

 

[Roedy Green]

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

 

[Marc van Dongen]

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

 

[John B. Matthews]

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.

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

 

[Tom Anderson]

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

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:

http://www.freebsd.org/cgi/man.cgi?...ion=0&manpath=FreeBSD+8.0-RELEASE&format=html

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

 

[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>