Traduction : Utilisation de la syntaxe Markdown dans les commentaires Javadoc

Utilisation de la syntaxe Markdown dans les commentaires Javadoc

Dans cet article, nous verrons comment rédiger des commentaires Javadoc en utilisant Markdown au lieu de la syntaxe Javadoc standard. Alors, qu’est-ce que le Markdown ? Markdown est un langage de balisage simple qui peut éventuellement être traduit en HTML à l'aide de l'outil du même nom. Markdown est largement utilisé pour formater les fichiers Lisez-moi, lors de la rédaction de messages sur le forum et dans les éditeurs de texte pour créer rapidement de superbes documents texte. (Wikipédia : Markdown ) Le texte formaté en Markdown est très facile à lire. Différentes versions de Markdown sont utilisées sur Stack Overflow ou GitHub pour formater le contenu généré par l'utilisateur.

Installation

Par défaut, l'outil Javadoc utilise les commentaires Javadoc pour générer la documentation API au format HTML. Ce processus peut être reconfiguré à l'aide de Doclets . Les doclets sont des programmes Java qui spécifient le contenu et le formatage du fichier de sortie de l'outil Javadoc. Markdown-doclet remplace le Java Doclet standard et donne ainsi au développeur la possibilité d'utiliser la syntaxe Markdown dans ses commentaires Javadoc. Vous pouvez l'installer dans Maven en utilisant maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Rédiger des commentaires dans Markdown

Vous pouvez désormais utiliser la syntaxe Markdown pour rédiger des commentaires Javadoc : /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } Après exécution

mvn javadoc:Javadoc

le document API HTML généré se trouve à l'adresse

cible/site/apidocs.

Le document généré pour le code ci-dessus ressemble à ceci : Comme vous pouvez le voir sur la figure, les commentaires Javadoc sont parfaitement convertis en HTML.

Conclusion

Markdown présente un net avantage par rapport à la syntaxe Javadoc standard : elle est beaucoup plus facile à lire dans le code source. Jetez simplement un œil à certains commentaires de méthode dans java.util.Map : beaucoup d’entre eux sont remplis de balises de formatage et sont difficiles à lire sans utiliser d’outils supplémentaires. Mais vous devez vous rappeler que Markdown peut causer des problèmes avec les outils et les IDE qui ne peuvent fonctionner qu'avec la syntaxe Javadoc standard. Source : Utilisation de la syntaxe Markdown dans les commentaires Javadoc de notre partenaire JCG Michael Scharhag du blog mscharhag, Programming and Stuff.