Quelle est la meilleure façon d'utiliser JavaDoc pour documenter une énumération Java?
Je viens de commencer à utiliser les énumérations de Java dans mes propres projets (je dois utiliser JDK 1.4 au travail) et je suis confus quant à la meilleure pratique d'utiliser JavaDoc pour une énumération.
J'ai trouvé que cette méthode fonctionne, mais le code résultant est un peu grossière:
/**
* Doc for enum
*/
public enum Something {
/**
* First thing
*/
FIRST_THING,
/**
* Second thing
*/
SECOND_THING;
//could continue with more
}
Est-il possible de casser les déclarations enum sur leurs propres lignes sans les enchaîner par des virgules, ou est-ce la meilleure approche pour utiliser JavaDoc pour une énumération?
3 réponses
Pour répondre à la première partie de votre question, vous devez séparer chaque valeur enum par une virgule. Autant que je sache, il n'y a pas moyen de contourner cela.
Personnellement, je n'ai pas de problème avec le code de la façon dont vous l'avez présenté. Semble être un moyen parfaitement raisonnable de documenter une énumération pour moi.
Comme Mike l'a mentionné, vous devez séparer les valeurs enum avec des virgules, et elles doivent être les premières choses listées dans la déclaration enum (les variables d'instance, les constantes, les constructeurs et les méthodes peuvent suivre).
Je pense que la meilleure façon de documenter les énumérations est similaire aux classes régulières: le type enum obtient une description de la fonction et du rôle de l'énumération dans son ensemble ("Something values are used to indicate which mode of operation a client wishes...") et chaque valeur enum obtient une description Javadoc de son but et de sa fonction ("FIRST_THING indicates that the operation should evaluate the first argument first..").
Si l'énumération les descriptions de valeurs sont courtes, vous pouvez les mettre sur une ligne comme /** Evaluate first argument first. */, mais je recommande de garder chaque valeur enum sur sa propre ligne. La plupart des IDE peuvent être configurés pour les formater de cette façon automatiquement.
Il existe un outil de recherche de code google en ligne -- http://www.google.com/codesearch
J'essaie de recherche de trucs en faisant quelque chose comme "lang:java public enum"