Java 23 Insight : écrivez votre Javadoc en Markdown !

Java 23 est attendu pour septembre 2024. Parmi les nouvelles fonctionnalités, la possibilité d'écrire la Javadoc en Markdown. Et ce n'est pas une preview !

JEP 467: Markdown Documentation Comments

On ne va pas se mentir, documenter son code est une tâche laborieuse et ennuyeuse, mais ô combien nécessaire ! Il vaut mieux que son écriture soit la plus simple possible.

La Javadoc

Le concept de Javadoc existe depuis les premières versions de Java. Elle consiste en une documentation écrite à l'intérieur du code dans un format standard, à partir duquel on peut générer une documentation sous différents formats, notamment HTML. On retrouve par exemple la Javadoc de Java ici. Elle liste l'intégralité des classes du JDK et toute leur documentation.

Il est très facile d'écrire sa propre Javadoc. Il suffit d'ouvrir les commentaires /** au-dessus d'une méthode ou classe, d'écrire la doc et de refermer avec */.

/**
 * Cette méthode fait des bulles en nombre et de taille données
 * @param nb le nombre de bulles
 * @param size la taille des bulles
 */
 void makeBubbles(int nb, int size);

Les mots-clés @param permettent d'avoir une cohérence avec le code et de tisser des liens vers d'autres parties de la Javadoc si possible. D'autres mots-clés existent comme @return ou @throws. Votre IDE peut bien souvent vous aider à générer ces paramètres.

Mise en forme

Dans les années 2000, le truc hype c'était le web et le HTML. Ainsi, pour mettre en forme la Javadoc, on utilise des balises HTML. Voici par exemple la Javadoc brute de la méthode hashCode de Object :

/**
 * Returns a hash code value for the object. This method is
 * supported for the benefit of hash tables such as those provided by
 * {@link java.util.HashMap}.
 * <p>
 * The general contract of {@code hashCode} is:
 * <ul>
 * <li>Whenever it is invoked on the same object more than once during
 *     an execution of a Java application, the {@code hashCode} method
 *     must consistently return the same integer, provided no information
 *     used in {@code equals} comparisons on the object is modified.
 *     This integer need not remain consistent from one execution of an
 *     application to another execution of the same application.
 * <li>If two objects are equal according to the {@link
 *     #equals(Object) equals} method, then calling the {@code
 *     hashCode} method on each of the two objects must produce the
 *     same integer result.
 * <li>It is <em>not</em> required that if two objects are unequal
 *     according to the {@link #equals(Object) equals} method, then
 *     calling the {@code hashCode} method on each of the two objects
 *     must produce distinct integer results.  However, the programmer
 *     should be aware that producing distinct integer results for
 *     unequal objects may improve the performance of hash tables.
 * </ul>
 *
 * @implSpec
 * As far as is reasonably practical, the {@code hashCode} method defined
 * by class {@code Object} returns distinct integers for distinct objects.
 *
 * @return  a hash code value for this object.
 * @see     java.lang.Object#equals(java.lang.Object)
 * @see     java.lang.System#identityHashCode
 */

Le résultat est visible ici. On voit bien l'utilisation des balises <p>, <ul>, <li>, etc. pour la mise en forme, ce qui peut vite devenir pénible.

Et maintenant en Markdown

Java 23 nous propose d'écrire la Javadoc en Markdown pour sa mise en forme. Pour rester compatible avec les anciennes Javadoc, on utilisera un triple slash pour spécifier une ligne de Javadoc. Pour le reste, voici la méthode hashCode en Markdown :

/// Returns a hash code value for the object. This method is
/// supported for the benefit of hash tables such as those provided by
/// [java.util.HashMap].
///
/// The general contract of `hashCode` is:
///
///   - Whenever it is invoked on the same object more than once during
///     an execution of a Java application, the `hashCode` method
///     must consistently return the same integer, provided no information
///     used in `equals` comparisons on the object is modified.
///     This integer need not remain consistent from one execution of an
///     application to another execution of the same application.
///   - If two objects are equal according to the
///     [equals][#equals(Object)] method, then calling the
///     `hashCode` method on each of the two objects must produce the
///     same integer result.
///   - It is _not_ required that if two objects are unequal
///     according to the [equals][#equals(Object)] method, then
///     calling the `hashCode` method on each of the two objects
///     must produce distinct integer results.  However, the programmer
///     should be aware that producing distinct integer results for
///     unequal objects may improve the performance of hash tables.
///
/// @implSpec
/// As far as is reasonably practical, the `hashCode` method defined
/// by class `Object` returns distinct integers for distinct objects.
///
/// @return  a hash code value for this object.
/// @see     java.lang.Object#equals(java.lang.Object)
/// @see     java.lang.System#identityHashCode

C'est quand même plus facile à écrire, vous ne trouvez pas ?