Where is the values() method documented for Enum?

[Dotan Cohen]

Enums have a handy values() method for running a foreach over:

for (Books b : Books.values()) {
    System.out.printf("%d", b.year);
}

I do not see that method documented:
http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/Enum.html

Where is that documented? Thanks!

[Rob Spoor]

It's added to each enum class automatically, and that's where it shows up. Check out TimeUnit for instance. The static valueOf(string) and values() methods are added to each enum class.

[Dotan Cohen]

Rob Spoor wrote:It's added to each enum class automatically, and that's where it shows up. Check out TimeUnit for instance. The static valueOf(string) and values() methods are added to each enum class.

Thanks, Rob, but how would one know that the method exists even? I understand that perhaps Eclipse or Netbeans might pop up "intellisense" where one could discover these hidden functions, but shouldn't all the functions be documented? By the way, I happen to code in VIM so no intellisense, but I would still like to learn the nuances of the values() method.

[Rob Spoor]

These two methods are documented in the enum classes. Like I said, just check the Javadoc page of any enum; TimeUnit, RoundingMode, every one has them.

[Steve Luke]

In addition, these methods are 'specially' inserted by the compiler, and not inherited from the parent class. You learn about these special methods because they are documented in the JLS: Section 8.9: Enum Types

[Dotan Cohen]

Thank you, I did not know to look up the feature in the JLS. Apparently google didn't know either

I will go through the JLS to learn when I should refer to it. I figured that the JLS was for those writing a Java compiler or runtime environment, not for application developers.

[Campbell Ritchie]

No, the JLS is for everybody. It’s just not always easy to understand

[Steve Luke]

Yeah, the JLS isn't an everyday reference like the API should be, but when you run into questions that the API does not address the JLS often will. It may be a dry read (<- understatement) but it is a good tool for the Java developer because it lays out all of the rules your programs run by. If you understand the rules then you can make better code to work with those rules, rather than work against them (or wonder why things behave the way they do).

[Joanne Neal]

The values() method is also mentioned in the Oracle tutorial which is a little easier to read than the JLS.

[Winston Gutkowski]

Dotan Cohen wrote:I do not see that method documented:
http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/Enum.html

I can sort of understand why they didn't include it as a method in the Enum class itself, but I'm with you Dotan, they could mention its existence specifically in the class documentation and point you directly to the relevant JLS paragraph (or indeed to a sample Enum class, such as RoundingMode). An oversight in my view, especially as "auto-generated" methods are quite rare.

Winston

[Joanne Neal]

Looks like the Javadoc has been updated for Java 7. The values() and valueOf(String) methods are both mentioned in the description of the valueOf(Class<T> , String) method.

[Rob Spoor]

Indeed it has.

[Dotan Cohen]

Joanne Neal wrote:The values() method is also mentioned in the Oracle tutorial which is a little easier to read than the JLS.

Thanks. That is actually one of the first google hits for the feature, and from where I got my "documentation" when I needed it.

[Campbell Ritchie]

Joanne Neal wrote: . . . Oracle tutorial . . .

But I still miss the bit about enums in other languages being only glorified integers. I suppose they had to take it out because it annoyed people who like “other languages”!

[Winston Gutkowski]

Campbell Ritchie wrote:I suppose they had to take it out because it annoyed people who like “other languages”!

Not to mention having to answer why it took 5 major releases to get one. Better late than never though .

Winston

[Campbell Ritchie]

That wasn’t the only thing which took 5 releases to implement.

[Rob Spoor]

And some things were implemented after 5 releases and still don't work as many want (generics - there shouldn't have been any type erasure).

[Dotan Cohen]

Joanne Neal wrote:Looks like the Javadoc has been updated for Java 7. The values() and valueOf(String) methods are both mentioned in the description of the valueOf(Class<T> , String) method.

Although values() is mentioned under valueOf(), why does it not have its own section? Surely this is an oversight. I am considering filing a bug on the docs but I feel that may be hasty considering that I am not so familiar with the Java docs yet. What do those more experienced than myself think? Should I file the bug?

[Joanne Neal]

I'm not sure but I think to have a method description in the javadoc, the method has to exist in the code, which obviously auto generated methods wont. If it isn't possible to have a method description for it, then I think that it should at least be mentioned in the main description rather than buried in another method's description.

[Winston Gutkowski]

Joanne Neal wrote:...I think that it should at least be mentioned in the main description rather than buried in another method's description.

Totally agree. And furthermore, the section referenced in the JLS (8.9) simply states (quite a long way down) that values() and valueOf(String) are automatically generated, with no explanation as to why; almost as though the docs were put in as an afterthought.

Perhaps a case for an "auto-generated" section in the Javadocs; maybe a bit like the constants section.

Winston