JEP 467 : commentaires de documentation Markdown
(openjdk.org)Objectif
Prendre en charge la syntaxe Markdown dans les commentaires de documentation Java afin d’améliorer la lisibilité et d’encourager une documentation plus concise.
Motivation
- Le JavaDoc existant repose sur des balises HTML → c’est trop verbeux et difficile à lire.
- Les développeurs sont déjà familiers avec Markdown via README, GitHub, etc.
- La prise en charge de Markdown permet de rédiger une documentation cohérente et concise.
Description
- Prise en charge de la syntaxe Markdown basée sur CommonMark dans les commentaires JavaDoc.
- Les commentaires HTML existants restent toujours utilisables.
- Au lieu des commentaires existants de type
/* ... */, utilisation de///pour indiquer qu’il s’agit de commentaires de documentation Markdown. - Les outils JavaDoc tiers effectuent l’analyse et le rendu du Markdown.
Spécification Markdown
- Basée sur CommonMark.
- Syntaxe prise en charge :
- Titres (
#,##,###, etc.) - Listes (ordonnées / non ordonnées)
- Blocs de code (```)
- Liens
- Tableaux (style Github Flavored Markdown)
- Citations
- Mise en valeur (
*italique*,**gras**)
- Titres (
Balises spécifiques à Java
Avec Markdown, il reste possible d’utiliser les balises @ de JavaDoc existantes :
@param@return@throws@see@since@deprecated
3 commentaires
Excellent...
On dirait que cela a été intégré à la norme.
Il est arrivé dans le JDK 23.
Après test, même si la version du JDK du projet est inférieure à 23, cela fonctionne normalement tant que l’IDE ou l’outil d’export Javadoc le prend en charge.