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?

Actually, at least for JDK1.7 (other versions not tested), it is completely legal to have a comma after *every* enum value, including the last one. Just put a semicolon on the line after the last value, and you're fine. This makes it easier to move values around or add/remove ones, without having to worry about using a comma or a semicolon. — Bart, Nov 14 '13 at 11:07

score 33 · Accepted Answer · answered Oct 12 '08 at 03:58

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.

score 14 · Answer 2 · answered Oct 12 '08 at 04:42

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.

score -3 · Answer 3 · edited Aug 21 '11 at 11:27

-3

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"

An example from Sun

edited Aug 21 '11 at 11:27

Marek Grzenkowicz

17,024
9
81
111

answered Oct 12 '08 at 04:16

anjanb

12,999
18
77
106

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

3 Answers3