Quel est le meilleur moyen d'utiliser JavaDoc pour documenter un enum Java?

Question

Je viens tout juste de commencer à utiliser les enums de Java dans mes propres projets (je dois utiliser JDK 1.4 au travail) et je suis confus quant à la meilleure pratique d'utilisation de JavaDoc pour une enum.

J'ai trouvé que cette méthode fonctionne, mais le code résultant est un peu non raffiné:

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

Existe-t-il un moyen de diviser les déclarations enum sur leurs propres lignes sans les enchaîner avec des virgules, ou est-ce la meilleure approche pour utiliser JavaDoc pour une enum?

Answer 1

Pour répondre à la première partie de votre question, vous devez séparer chaque valeur enum par une virgule. Pour autant que je sache, il n'y a aucun moyen de contourner cela.

Personnellement, je n'ai pas de problème avec le code tel que vous l'avez présenté. Cela semble être un moyen parfaitement raisonnable de documenter une énumération pour moi.

Answer 2

Comme Mike l'a mentionné, vous n'avez pas à séparer les valeurs enum par des virgules, et ils ont à être la première des choses énumérées dans la déclaration d'enum (exemple des variables, des constantes, des constructeurs et des méthodes à suivre).

Je pense que la meilleure façon de documenter les énumérations est similaire aux classes ordinaires: le type enum obtient une description de la fonction et le rôle de l'enum ("Something values are used to indicate which mode of operation a client wishes...") et chaque valeur d'enum obtient une Javadoc description de son objet et de la fonction ("FIRST_THING indicates that the operation should evaluate the first argument first..").

Si la valeur d'enum descriptions sont courtes vous pourriez vous voulez les mettre sur une seule ligne comme /** Evaluate first argument first. */, mais je vous recommande de veiller à ce que chaque valeur d'enum sur sa propre ligne. La plupart des IDEs peut être configuré pour le format de cette façon automatique.

Answer 3

checkstyle indique "commentaire JavaDoc manquant" dans votre exemple. Je ne sais pas encore comment le réparer, je posterai un peu plus tard ...

Answer 4

Il existe un outil en ligne de recherche de code Google - http://www.google.com/codesearch

J'essaie de chercher des choses en faisant quelque chose comme "lang: java public enum"

Un exemple de Sun