Java 25

Java 25 : Markdown dans Javadoc (JEP 467)

Avec Java 25, la JEP 467 introduit le support du Markdown dans les commentaires de documentation Javadoc. Cette fonctionnalité permet d'écrire une documentation plus lisible, plus facile à maintenir, en utilisant la syntaxe /// au lieu des traditionnels /** */.

Cette nouveauté fait partie des JEPs (Java Enhancement Proposals) finalisées dans Java 25.

Pourquoi Markdown dans Javadoc ?

La documentation Javadoc traditionnelle utilise du HTML pour le formatage. Bien que puissant, ce format a des inconvénients :

  • Verbosité : <p>, <ul>, <li> pour des éléments simples
  • Lisibilité réduite : le HTML dans le code source est difficile à lire
  • Courbe d'apprentissage : les développeurs doivent connaître les tags Javadoc ET le HTML
  • Incohérences : le mélange de tags Javadoc et HTML peut créer des conflits

Comparaison visuelle

// Javadoc traditionnel (HTML)
/**
 * Calcule la factorielle d'un nombre.
 * <p>
 * Cette méthode utilise une approche récursive pour calculer n!
 * </p>
 * <p>
 * <strong>Attention</strong>: pour les grandes valeurs, utilisez
 * {@link BigInteger} pour éviter le dépassement.
 * </p>
 *
 * @param n le nombre dont on calcule la factorielle
 * @return la factorielle de n
 * @throws IllegalArgumentException si n est négatif
 * @see BigInteger#factorial()
 */
public long factorielle(int n) { ... }

// Javadoc Markdown (Java 25)
/// Calcule la factorielle d'un nombre.
///
/// Cette méthode utilise une approche récursive pour calculer n!
///
/// **Attention**: pour les grandes valeurs, utilisez
/// [BigInteger] pour éviter le dépassement.
///
/// @param n le nombre dont on calcule la factorielle
/// @return la factorielle de n
/// @throws IllegalArgumentException si n est négatif
/// @see BigInteger#factorial()
public long factorielle(int n) { ... }

Syntaxe des commentaires Markdown

Le préfixe ///

Les commentaires de documentation Markdown utilisent le préfixe /// : 

/// Ceci est un commentaire de documentation Markdown.
/// Chaque ligne commence par trois slashes.
///
/// Les paragraphes sont séparés par une ligne vide.
public void maMethode() { }

Le style traditionnel /** */ continue de fonctionner avec HTML. Vous pouvez utiliser les deux styles dans le même projet.

Formatage de texte

/// # Titre de niveau 1
/// ## Titre de niveau 2
/// ### Titre de niveau 3
///
/// Texte **en gras** et *en italique*.
///
/// Texte `en code inline`.
///
/// ~~Texte barré~~

Listes

/// Liste non ordonnée:
/// - Premier élément
/// - Deuxième élément
///   - Sous-élément
/// - Troisième élément
///
/// Liste ordonnée:
/// 1. Première étape
/// 2. Deuxième étape
/// 3. Troisième étape

Blocs de code

/// Exemple d'utilisation:
///
/// ```java
/// Calculator calc = new Calculator();
/// int result = calc.add(2, 3);
/// System.out.println(result); // 5
/// ```
///
/// Vous pouvez aussi utiliser du code inline: `calc.add(a, b)`

Liens

/// Voir la [documentation officielle](https://docs.oracle.com).
///
/// Référence à une autre classe: [String]
/// Référence à une méthode: [String#length()]
/// Référence avec texte: [la méthode length][String#length()]
///
/// Lien vers une section: [#maMethode()]

Citations et notes

/// > **Note**: Cette méthode est thread-safe.
///
/// > **Attention**: Ne pas utiliser avec des valeurs null.

Tableaux

/// | Paramètre | Type | Description |
/// |-----------|------|-------------|
/// | nom | String | Le nom de l'utilisateur |
/// | age | int | L'âge en années |
/// | email | String | L'adresse email |

Tags Javadoc dans Markdown

Les tags Javadoc classiques (@param, @return, etc.) fonctionnent normalement dans les commentaires Markdown : 

/// Calcule la somme de deux nombres.
///
/// Cette méthode effectue une addition simple. Elle gère
/// correctement les cas de dépassement en lançant une exception.
///
/// ## Exemple
/// ```java
/// int resultat = additionner(5, 3); // 8
/// ```
///
/// @param a le premier opérande
/// @param b le second opérande
/// @return la somme de a et b
/// @throws ArithmeticException si le résultat dépasse Integer.MAX_VALUE
/// @since 25
/// @see Math#addExact(int, int)
public int additionner(int a, int b) {
    return Math.addExact(a, b);
}

Documentation de classes et interfaces

/// Service de gestion des utilisateurs.
///
/// Ce service fournit les opérations CRUD pour les utilisateurs
/// de l'application. Il est **thread-safe** et peut être utilisé
/// dans un contexte concurrent.
///
/// ## Utilisation
///
/// ```java
/// UserService service = new UserService(repository);
/// User user = service.findById(123L);
/// ```
///
/// ## Configuration
///
/// Le service nécessite un [UserRepository] pour fonctionner.
/// Voir [#configure(Config)] pour les options de configuration.
///
/// @author Jean Dupont
/// @version 2.0
/// @since 25
public class UserService {

    /// Recherche un utilisateur par son identifiant.
    ///
    /// @param id l'identifiant unique de l'utilisateur
    /// @return l'utilisateur trouvé
    /// @throws UserNotFoundException si aucun utilisateur n'existe avec cet id
    public User findById(Long id) { ... }

    /// Crée un nouvel utilisateur.
    ///
    /// Les champs suivants sont **obligatoires**:
    /// - `email`: doit être unique et valide
    /// - `password`: minimum 8 caractères
    ///
    /// @param user l'utilisateur à créer (sans id)
    /// @return l'utilisateur créé avec son id généré
    public User create(User user) { ... }
}

Documentation d'enums

/// Représente le statut d'une commande.
///
/// Le cycle de vie d'une commande suit ces transitions:
///
/// ```
/// PENDING -> CONFIRMED -> SHIPPED -> DELIVERED
///                     \-> CANCELLED
/// ```
public enum OrderStatus {

    /// Commande en attente de confirmation.
    /// Le paiement n'a pas encore été validé.
    PENDING,

    /// Commande confirmée et en préparation.
    /// Le paiement a été accepté.
    CONFIRMED,

    /// Commande expédiée.
    /// Un numéro de suivi est disponible via [Order#getTrackingNumber()].
    SHIPPED,

    /// Commande livrée au client.
    DELIVERED,

    /// Commande annulée.
    /// Voir [Order#getCancellationReason()] pour la raison.
    CANCELLED
}

Documentation de Records

/// Représente un point dans un espace 2D.
///
/// Cette classe est **immuable** et thread-safe.
///
/// ## Exemples
///
/// ```java
/// Point origin = new Point(0, 0);
/// Point p = new Point(3, 4);
/// double dist = p.distanceTo(origin); // 5.0
/// ```
///
/// @param x la coordonnée x
/// @param y la coordonnée y
public record Point(double x, double y) {

    /// Calcule la distance euclidienne vers un autre point.
    ///
    /// Utilise la formule: √((x₂-x₁)² + (y₂-y₁)²)
    ///
    /// @param other le point cible
    /// @return la distance entre les deux points
    public double distanceTo(Point other) {
        double dx = other.x - this.x;
        double dy = other.y - this.y;
        return Math.sqrt(dx * dx + dy * dy);
    }
}

Génération de la Javadoc

La génération de la documentation fonctionne comme avant : 

# Génération standard
javadoc -d docs src/*.java

# Avec Maven
mvn javadoc:javadoc

# Avec Gradle
./gradlew javadoc

Le résultat HTML est identique, que vous utilisiez la syntaxe HTML ou Markdown.

Migration progressive

Vous n'êtes pas obligé de convertir toute votre documentation d'un coup. Les deux styles coexistent parfaitement : 

/**
 * Documentation existante en HTML.
 * <p>Reste valide et fonctionnelle.</p>
 */
public void ancienneMethode() { }

/// Nouvelle documentation en Markdown.
///
/// Plus lisible et facile à maintenir.
public void nouvelleMethode() { }

Stratégie de migration recommandée

  1. Utilisez Markdown pour tout nouveau code
  2. Convertissez progressivement lors des modifications
  3. Priorisez les API publiques
  4. Utilisez des outils de conversion automatique si disponibles

Bonnes pratiques

  • Soyez concis : Markdown encourage la brièveté
  • Utilisez les exemples de code : les blocs ``` sont très lisibles
  • Structurez avec des titres : ## pour les sections importantes
  • Préférez les listes : plus lisibles que les paragraphes longs
  • Gardez les @tags : ils restent la meilleure façon de documenter les paramètres

Support des IDEs

Les principaux IDEs supportent la documentation Markdown :

  • IntelliJ IDEA 2025.2+ : rendu Markdown dans les popups de documentation
  • Eclipse 2025-09+ : support via plugin
  • VS Code : extension Java mise à jour

Conclusion

Le support Markdown dans Javadoc (JEP 467) est une amélioration de qualité de vie pour les développeurs Java. La documentation devient plus agréable à écrire et à lire directement dans le code source, tout en produisant la même sortie HTML de qualité.

Pour les nouveaux projets Java 25, adoptez la syntaxe /// dès le départ. Pour les projets existants, migrez progressivement lors des mises à jour de code.

Ressources