¿Cuál es la mejor forma de usar JavaDoc para documentar una enumeración de Java?

Question

Acabo de empezar a usar las enumeraciones de Java en mis propios proyectos (tengo que usar JDK 1.4 en el trabajo) y estoy confundido en cuanto a la mejor práctica de usar JavaDoc para una enumeración.

he encontrado que este método funciona, pero el código resultante es un poco sin refinar:

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

¿Hay alguna manera de que pudiera romper las declaraciones de enumeración en sus propias líneas sin encadenándolos por comas, o ¿Es este el mejor método para usar JavaDoc para una enumeración?

Answer 1

Para responder a la primera parte de su pregunta, debe separar cada valor de enumeración con una coma. Hasta donde yo sé, no hay forma de evitar eso.

Personalmente no tengo un problema con el código de la forma en que lo ha presentado. Parece una forma perfectamente razonable de documentarme una enumeración.

Answer 2

Hay una búsqueda de google código de la herramienta en línea - http://www.google.com/codesearch

trato de las operaciones de búsqueda cosas por hacer algo como "lang:java public enum"

An example from Sun

Answer 3

Como se mencionó Mike, usted tiene que separar los valores de enumeración con comas, y tienen que ser las primeras cosas enumeradas en la declaración enum (variables de instancia, constantes, constructores y métodos pueden seguir).

Creo que la mejor manera de documentar enumeraciones es similar a las clases regulares: el tipo enum obtiene una descripción de la función y el rol de la enumeración como un todo ("Something values are used to indicate which mode of operation a client wishes...") y cada valor enum obtiene una descripción Javadoc propósito y función ("FIRST_THING indicates that the operation should evaluate the first argument first..").

Si las descripciones de los valores enum son cortas, puede colocarlas en una línea como /** Evaluate first argument first. */, pero recomiendo mantener cada valor enum en su propia línea. La mayoría de los IDE se pueden configurar para formatearlos de esta manera automáticamente.