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

java enums javadoc
MetroidFan2002 picture MetroidFan2002 · Oct 12, 2008 · Viewed 20.3k times · Source

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

Mike Deck picture Mike Deck · Oct 12, 2008

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.

Related questions

How to Javadoc a Class's Individual Enums

I am writing the javadoc for a class that contains it's own enums. Is there a way to generate javadoc for the individual enums? For example, right now I have something like this: /** * This documents "HairColor" */ private static enum HairColor { …

Read More
How to get an enum value from a string value in Java?

Say I have an enum which is just public enum Blah { A, B, C, D } and I would like to find the enum value of a string, for example "A" which would be Blah.A. How would it be possible …

Read More
Comparing Java enum members: == or equals()?

I know that Java enums are compiled to classes with private constructors and a bunch of public static members. When comparing two members of a given enum, I've always used .equals(), e.g. public useEnums(SomeEnum a) { if(a.equals(…

Read More