JEP 467: Comentarios de documentación en Markdown

Objetivo

Dar soporte a la sintaxis Markdown en los comentarios de documentación de Java para mejorar la legibilidad y fomentar una documentación más concisa.

Motivación

• El JavaDoc existente depende de etiquetas HTML → es demasiado verboso y difícil de leer.
• Los desarrolladores ya están familiarizados con Markdown en README, GitHub y otros entornos.
• Con soporte para Markdown, es posible redactar documentación consistente y concisa.

Descripción

• Soporte para la sintaxis Markdown basada en CommonMark dentro de los comentarios de JavaDoc.
• Los comentarios HTML existentes siguen siendo utilizables.
• En lugar del estilo de comentarios existente /* ... */, se usa /// para indicar que se trata de un comentario de documentación en Markdown.
• Las herramientas JavaDoc de terceros procesan el parseo y el renderizado de Markdown.

Especificación de Markdown

• Basada en CommonMark.
• Sintaxis compatible:
  • Encabezados (#, ##, ###, etc.)
  • Listas (ordenadas/no ordenadas)
  • Bloques de código (```)
  • Enlaces
  • Tablas (al estilo de Github Flavored Markdown)
  • Citas
  • Énfasis (*cursiva*, **negritas**)

Etiquetas específicas de Java

Junto con Markdown, también se pueden usar las etiquetas @ existentes de JavaDoc:

• @param
• @return
• @throws
• @see
• @since
• @deprecated

[devnamho0910]

Excelente...

[carnoxen]

Parece que fue incorporado al estándar.

[click]

Se incluyó en JDK 23.
Al probarlo, funciona correctamente incluso si la versión de JDK del proyecto es inferior a 23, siempre que el IDE o la herramienta de exportación de Javadoc lo admitan.