//NextPatch
Perfil

Java 22 → 23: tres finales y un preview que desaparece · Javadoc en Markdown

Javadoc en Markdown en Java 23: comentarios /// sin HTML

Cargando la lección…

Guarda tu racha: crea tu cuenta

Este reto se sumará a tu cuenta nueva: su XP y tu primer día de racha. Luego, uno nuevo cada día para preparar tu próxima entrevista.

Los comentarios de documentación de Java mezclan HTML con etiquetas @ de JavaDoc desde 1995. Entonces el HTML era una elección razonable; hoy es tedioso de escribir y difícil de leer en el propio código. Un análisis del código fuente del JDK encontró que más del 95 % de las etiquetas en línea eran solo fragmentos de código y enlaces.

Qué añade Java 23

El JEP 467, final en Java 23, añade una segunda forma de comentario de documentación: cada línea empieza por /// y el contenido se interpreta como Markdown CommonMark.

java
/// Envía la petición y reintenta si falla.
///
/// Como mucho `maxRetries` intentos, y _nunca_ ante una respuesta 4xx.
///
/// - Ver [java.net.http.HttpClient].
///
/// @return la respuesta final
HttpResponse<String> send() { ... }

Lo que desaparece

  • <p>: una línea en blanco, que se escribe poniendo solo ///, separa párrafos.
  • <ul> y <li>: un guion al principio de línea abre un elemento de lista.
  • <em>: los guiones bajos cambian el estilo de letra.
  • {@code x}: unas comillas invertidas hacen el mismo trabajo.
  • {@link ...}: un enlace a otro elemento se escribe entre corchetes.

Las etiquetas de bloque, como @param, @return o @see, siguen igual y van al final, como siempre.

Por qué tres barras

No se reutilizó /** */ por dos motivos. Un bloque /* */ no puede contener su propia secuencia de cierre, que en Markdown puede aparecer. Y dentro de un /** */ los asteriscos al principio de cada línea son opcionales, lo que choca con las construcciones de Markdown que empiezan por asterisco, como las listas.

No se rompe nada

Los comentarios /** ... */ con HTML siguen funcionando exactamente igual, y dentro de un comentario /// se admite HTML para lo que Markdown no cubra. Puedes migrar poco a poco, o no migrar: las dos formas conviven en el mismo proyecto.