Crear anotaciones de Javadoc personalizadas con taglets

Publicado por pico.dev el .
blog-stack java planeta-codigo" programacion
Comentarios

Java

La herramienta de documentación es Javadoc de Java permite a partir del código fuente de un programa o librería generar un conjunto de documentos en formato HTML enlazados entre si consultables con un navegador web y accesibles desde internet si son accesibles con un servidor web. La documentación se genera a partir de las clases y métodos del código fuente y también a partir de los comentarios de las clases y métodos.

En los comentarios se pueden incluir anotaciones que enriquecen la documentación, por ejemplo, para indicar el autor o en qué versión se incluyó una clase o método, incluir enlaces, … en el propio JDK ya se incluye un amplio conjunto completo de anotaciones. Pero además de usar las anotaciones ya incorporados por defecto en la herramienta también es posible añadir nuevos propios, escribiendo un taglet. Con la API de los taglets basta implementar una clase que implemente la interfaz Taglet. La interfaz Taglet de Java 9 ha sido modificada ligeramente pero en esencia proporciona la misma información, en vez de un método para indicar si es posible el taglet en una localización hay un único método que devuelve un Set con todas las posibles localizaciones, en vez de necesitar un método register hay un método init y un único método para generar el contenido, toString.

La clase tiene varios métodos uno que indica el nombre único del taglet que identificará la anotación en los comentarios de Javadoc, varios métodos para indicar en que localizaciones es usable y dos métodos que generan el contenido a incluir en el HTML resultante. Las clases Tag que recibe el método Taglet.toString() o ParamTag permite obtener diversa información utilizable para generar el contenido apropiado.

Los taglets pueden ser de tipo bloque con su propia entidad o ser embebidos en linea en un comentario del javadoc. En ejemplo de taglet de bloque siguiente consiste en permitir incluir elementos que quedan por hacer en el código, una anotación todo. Con esta anotación el desarrollador incluye un comentario descriptivo de cuales son las cosas pendientes para un futuro. El código del taglet sería el siguiente.

}

Una vez escrito el código fuente del taglet hay que compilarlo e indicar su ubicación al generar la documentación con la herramienta javadoc. Hay que indicar varias opciones (tagletPath y taglets) que también se usarían como parámetros empleando directamente la herramienta javadoc, los comandos serían los siguientes usando Gradle. También hay que incluir de forma explícita como dependencia la librería tools.jar ubicado en el JDK.

}

Contenido del taglet todo en el javadoc

El código fuente completo del ejemplo puedes descargarlo del repositorio de ejemplos de Blog Bitix alojado en GitHub y probarlo en tu equipo ejecutando el comando ./gradlew javadoc.

Yo apoyo al software libre