What is the best way to use JavaDoc to document a Java enum?

Question

I've just started using Java's enums in my own projects (I have to use JDK 1.4 at work) and I am confused as to the best practice of using JavaDoc for an enum.

I have found that this method works, but the resultant code is a little unrefined:

/**
* Doc for enum
*/
public enum Something {
/**
* First thing
*/
FIRST_THING,
/**
* Second thing
*/
SECOND_THING;
//could continue with more
}

Is there any way I could break up the enum declarations on their own lines without chaining them by commas, or is this the best approach for using JavaDoc for an enum?

Answer 1

To answer the first part of your question, you do have to separate each enum value with a comma. As far as I know, there's no way around that.

Personally I don't have a problem with the code the way you've presented it. Seems like a perfectly reasonable way to document an enum to me.

Answer 2

there is a google code search online tool -- http://www.google.com/codesearch

I try to lookup stuff by doing something like "lang:java public enum" (http://www.google.com/codesearch?q=lang%3Ajava+public+enum&hl=en&btnG=Search+Code)

an example from sun here : http://is.gd/3UBZ

here was my google code search for the above link : http://www.google.com/codesearch?hl=en&lr=&q=public+enum+lang%3Ajava+&sbtn=Search

Answer 3

As Mike mentioned, you do have to separate the enum values with commas, and they have to be the first things listed in the enum declaration (instance variables, constants, constructors and methods may follow).

I think the best way to document enums is similar to regular classes: the enum type gets a description of the function and role of the enum as a whole ("Something values are used to indicate which mode of operation a client wishes...") and each enum value gets a Javadoc description of its purpose and function ("FIRST_THING indicates that the operation should evaluate the first argument first..").

If the enum value descriptions are short you might want to put them on one line as /** Evaluate first argument first. */, but I recommend keeping each enum value on its own line. Most IDEs can be configured to format them this way automatically.