Traducción: uso de la sintaxis de Markdown en comentarios de Javadoc

Uso de la sintaxis de Markdown en comentarios de Javadoc

En esta publicación, veremos cómo escribir comentarios Javadoc usando Markdown en lugar de la sintaxis estándar de Javadoc. Entonces, ¿qué es Markdown? Markdown es un lenguaje de marcado simple que, opcionalmente, se puede traducir a HTML utilizando la herramienta del mismo nombre. Markdown se usa ampliamente para formatear archivos Léame, al escribir publicaciones en foros y en editores de texto para crear rápidamente hermosos documentos de texto. (Wikipedia: Markdown ) El texto formateado en Markdown es muy fácil de leer. Se utilizan varios tipos de Markdown en Stack Overflow o GitHub para formatear el contenido generado por el usuario.

Instalación

De forma predeterminada, la herramienta Javadoc utiliza comentarios de Javadoc para generar documentación API como HTML. Este proceso se puede reconfigurar mediante Doclets . Los doclets son programas Java que especifican el contenido y el formato del archivo de salida de la herramienta Javadoc. Markdown-doclet reemplaza el Doclet Java estándar y, por lo tanto, brinda al desarrollador la capacidad de utilizar la sintaxis de Markdown en sus comentarios de Javadoc. Puede instalarlo en Maven usando maven-javadoc-plugin. maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Escribir comentarios en Markdown

Ahora puede utilizar la sintaxis de Markdown para escribir comentarios de Javadoc: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } después de la ejecución

mvn javadoc:Javadoc

el documento HTML API generado se encuentra en

destino/sitio/apidocs.

El documento generado para el código anterior se ve así: Como puede ver en la figura, los comentarios de Javadoc se convierten perfectamente a HTML.

Conclusión

Markdown tiene una clara ventaja sobre la sintaxis estándar de Javadoc: es mucho más fácil de leer en el código fuente. Basta con echar un vistazo a algunos de los comentarios de métodos en java.util.Map: muchos de ellos están llenos de etiquetas de formato y son difíciles de leer sin utilizar herramientas adicionales. Pero hay que recordar que Markdown puede causar problemas con herramientas e IDE que sólo pueden funcionar con la sintaxis estándar de Javadoc. Fuente: Uso de la sintaxis de Markdown en comentarios de Javadoc de nuestro socio de JCG , Michael Scharhag, del blog mscharhag, Programming and Stuff.