octobre
2006
Un article de adiGuba
Je viens juste de tomber sur une petite astuce javadoc bien pratique !
Comme vous devez sans doute le savoir (en tout cas je l’espère), les commentaires javadoc sont utilisés pour générer la documentation HTML de vos classes, et on peut donc utiliser les tags HTML pour formater nos commentaire comme bon nous semble…
Toutefois, cela pose un léger problème : certains caractères doivent être encodé de manière spécifique. Ainsi par exemple, pour représenter les symboles inférieurs et supérieurs ( < > ) il est nécessaire d’utiliser une syntaxe quelque peu barbare, c’est à dire respectivement < et >… Ce qui ne se révèle pas très pratique ni lisible (surtout dans un exemple de code source !).
Mais le principal problème vient du fait que tout ce qui se trouve entre ces deux caractères sera ignoré par le moteur de rendu HTML, car il considérera qu’il s’agit d’une balise inconnu. Donc si vous vouliez affiché dans votre commentaire List<Integer> vous vous retrouverez à l’affichage avec un simple List bien moins instructif…
Pour combler cela, la javadoc de Java 5.0 utilise donc désormais deux nouveaux tags se chargeant de transformer automatiquement les caractères dans leurs codes équivalents.
- @literal permet ainsi de transformer automatiquement ces caractères.
- @code permet la même chose tout en leurs appliquant le style spécifique des codes sources, c’est à dire en entourant le tout d’une balise <code> (généralement cela se traduit par l’utilisation d’une police de taille fixe).
Mais comme une bonne démo vaut toutes les explications du monde, si votre commentaire javadoc contient ceci :
List<Integer><br/>
{@literal List<Integer>}<br/>
{@code List<Integer>}<br/>
Vous obtiendrez au final le résultat suivant :
List
List
List<Integer>
3 Commentaires + Ajouter un commentaire
Tutoriels
Discussions
- [REFLEXION] Connaitre toutes les classes qui implémentent une interface
- L'apparition du mot-clé const est-il prévu dans une version à venir du JDK?
- Classes, méthodes private
- Définition exacte de @Override
- [ fuite ] memoire
- Recuperation du nom des parametres
- Possibilité d'accéder au type générique en runtime
- Difference de performances Unix/Windows d'un programme?
- jre 1.5, tomcat 6.0 et multi processeurs
Je dois avouer que j’ai moi aussi découvert cette astuce aujourd’hui
Merci pour ce truc que je ne connaissais pas !
Grrrrr, je suis en train de me rendre compte que je n’avais pas pensé au fait que mes declarations de generics n’allaient pas passer dans la javadoc…
en tout cas, merci pour tes deux astuces