Win a copy of Kotlin in Action this week in the Kotlin forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic

Method missing in JavaDoc for Enum  RSS feed

 
Kartik Patel
Ranch Hand
Posts: 73
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
I found that in J2SE1.5 javadoc , there is no method called values() in java.lang.Enum. I know this method is available to the class generated by compiler from enum.

Don't you think it is a bad way and it enforces users to know how compiler modifies perticular piece of code? as developer may not be aware that any method called values() is being aded by compiler at the time of generating class from enum?
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Where could they document this in the JavaDoc? The values() and valueOf() methods are static methods of the enum types which you write. They don't belong in the Enum class; they belong in each and every individual Enum subclass. Sun can't possibly document code that hasn't even been written yet.

Similarly, arrays have a member called "length". You won't find any JavaDoc for this, because it's something added to all arrays everywhere. It's part of the "magic" behavior that Java's creators built into the language. You learn about it when you learn the basics of how to use arrays in Java. The values() and valueOf() methods for enums are the same way; they should be described in any book or article that covers how to use Java enums.

In retrospect, Sun could have created a base class Array that all arrays implicitly extend, and then put a length() method in that class. But they didn't think to design things that way. In comparison, with Enum they can't define values() and valueOf() in the Enum class, because those methods are necessarily static. So those methods are covered by special rules, outside the API.
 
Garrett Rowe
Ranch Hand
Posts: 1296
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Where could they document this in the JavaDoc?
They could have at least mentioned in the docs for Enum class.
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
But the methods aren't part of the Enum class. We could just as well say that they could have mentioned them in the docs for the Object class. Fundamentally, these methods are language features, not library features. Thus they're described in the JLS rather than the API. And in books and articles on enums. The API is not responsible for describing everything about Java. It's just responsible for describing the standard libraries.
 
It is sorta covered in the JavaRanch Style Guide.
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!