wood burning stoves*
The moose likes Beginning Java and the fly likes Where is the values() method documented for Enum? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Where is the values() method documented for Enum?" Watch "Where is the values() method documented for Enum?" New topic
Author

Where is the values() method documented for Enum?

Dotan Cohen
Ranch Hand

Joined: Feb 09, 2011
Posts: 40
Enums have a handy values() method for running a foreach over:


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
Sheriff

Joined: Oct 27, 2005
Posts: 19762
    
  20

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.


SCJP 1.4 - SCJP 6 - SCWCD 5 - OCEEJBD 6
How To Ask Questions How To Answer Questions
Dotan Cohen
Ranch Hand

Joined: Feb 09, 2011
Posts: 40
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
Sheriff

Joined: Oct 27, 2005
Posts: 19762
    
  20

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
Bartender

Joined: Jan 28, 2003
Posts: 4181
    
  21

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


Steve
Dotan Cohen
Ranch Hand

Joined: Feb 09, 2011
Posts: 40
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
Sheriff

Joined: Oct 13, 2005
Posts: 39869
    
  28
No, the JLS is for everybody. It’s just not always easy to understand
Steve Luke
Bartender

Joined: Jan 28, 2003
Posts: 4181
    
  21

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
Rancher

Joined: Aug 05, 2005
Posts: 3739
    
  16
The values() method is also mentioned in the Oracle tutorial which is a little easier to read than the JLS.


Joanne
Winston Gutkowski
Bartender

Joined: Mar 17, 2011
Posts: 8245
    
  23

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


Isn't it funny how there's always time and money enough to do it WRONG?
Articles by Winston can be found here
Joanne Neal
Rancher

Joined: Aug 05, 2005
Posts: 3739
    
  16
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
Sheriff

Joined: Oct 27, 2005
Posts: 19762
    
  20

Indeed it has.
Dotan Cohen
Ranch Hand

Joined: Feb 09, 2011
Posts: 40
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
Sheriff

Joined: Oct 13, 2005
Posts: 39869
    
  28
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
Bartender

Joined: Mar 17, 2011
Posts: 8245
    
  23

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
Sheriff

Joined: Oct 13, 2005
Posts: 39869
    
  28
That wasn’t the only thing which took 5 releases to implement.
Rob Spoor
Sheriff

Joined: Oct 27, 2005
Posts: 19762
    
  20

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
Ranch Hand

Joined: Feb 09, 2011
Posts: 40
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
Rancher

Joined: Aug 05, 2005
Posts: 3739
    
  16
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
Bartender

Joined: Mar 17, 2011
Posts: 8245
    
  23

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
 
Don't get me started about those stupid light bulbs.
 
subject: Where is the values() method documented for Enum?