La herramienta de documentación Javadoc de Java

Programar y desarrollar requiere además de poseer diversos conocimientos disponer de una buena documentación de consulta y referencia. Una de las cosas buenas que me gustaron de Java cuando empecé a programar en este lenguaje, cuando aún estaba lejos de tener internet y aún me lo sigue pareciendo, fue su documentación Javadoc de toda la API de clases incluidas en el JDK.

La documentación Javadoc es una colección de páginas HTML de todas las clases, métodos, parámetros y retornos junto con la información y especificaciones que quiera incluir el desarrollador de la API que en el caso de las clases de JDK incluye abundantes e interesantes detalles de implementación a tener en cuenta al usar las clases. El Javadoc es también es una herramienta de línea de comandos que permite generar la colección de páginas HTML a partir del código fuente Java.

Se genera a partir del propio código fuente de las clases con los comentarios incluidos que siguen cierto formato precediendo la definición de las clases y métodos. Al estar código y documentación en el propio archivo de código fuente es más fácil mantener sincronizados el código y su documentación.

La documentación en el código fuente se incluye en comentarios que preceden una clase o método, además, con anotaciones se pueden documentar los parámetros y el valor de retorno. Se pueden incluir etiquetas HTML junto con algunas de las anotaciones o doclets/taglets, algunas anotaciones Javadoc incluidas en el JDK son las siguientes pero también se pueden desarrollar doclets/taglets propios o personalizar los estilos de la documentación para cambiar el contenido, información incluida o adaptar los estilos a unos según los colores de la organización.

• @author: indica el autor de la clase o método.
• {@code}: incluye en el comentario un trozo de código que se formatea de forma especial.
• {@docRoot}: incluye una ruta relativa al directorio raíz donde se genera la documentación.
• @deprecated: indica que un método ha quedado obsoleto, se desaconseja su uso y puede que en futuras versiones desaparezca.
• @exception: es sinónima de throws.
• {@inheritDoc}: hereda el comentario Javadoc de la clase o método superior en la jerarquía de clases.
• {@link}: incluye un enlace a otra sección de la documentación, método o clase.
• {@linkplain}: es idéntica a @link pero el enlace es un texto plano.
• {@literal}: muestra un texto sin interpretar el texto como HTML.
• @param: documenta un parámetro de un método.
• @return: documenta el valor de retorno de un método.
• @see: incluye un enlace con documentación adicional en la sección final de la documentación.
• @serial
• @serialData
• @serialField
• @since: indica a partir de que versión de la API fue incluida la clase o método.
• @throws: documenta una posible excepción que puede ser lanzada por el método.
• {@value}: muestra el valor de un campo estático.
• @version: para documentar la versión de cuando se hizo checkout del sistema de control de versiones.

Un ejemplo usando estas anotaciones en una clase sería el siguiente.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

package io.github.picodotdev.blogbitix.javadoc;

/**
 * Clase main de la aplicación.
 *
 * @see <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html">Javadoc</a>
 * @see <a href="https://docs.oracle.com/javase/8/docs/api/">Javadoc JDK</a>
 * @author picodotdev
 * @version 1.0
 */
public class Main {

    /**
     * Método que imprime un mensaje.
     * 
     * @param args Argumentos del programa
     */
    public static void main(String[] args) {
      System.out.println("Hola mundo");
    }
}

Una vez documentado el código fuente hay que usar la herramienta Javadoc para generar la documentación. Mediante la herramienta de construcción Gradle se hace con la tarea javadoc.

1
2

$ ./gradlew javadoc

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

apply plugin: 'java'
apply plugin: 'application'

sourceCompatibility = 1.8
targetCompatibility = 1.8

mainClassName = 'io.github.picodotdev.blogbitix.javadoc.Main'

repositories {
	mavenCentral()
}

dependencies {
}

javadoc {
    options.charSet = 'UTF-8'
    options.encoding = 'UTF-8'
}

task zipJavadoc(type: Zip) {
    dependsOn javadoc
    classifier 'javadoc'
    from 'build/docs/javadoc/'
}

artifacts {
    archives zipJavadoc
}

La propia documentación de las clases del JDK está generada con la herramienta Javadoc. Este es el aspecto de la documentación de este ejemplo que tiene exactamente el mismo aspecto que la del JDK.

La documentación Javadoc al ser una colección de archivos HTML y demás recursos estáticos pueden copiarse a cualquier servidor web si es necesario que estén disponibles a través de internet y accesibles con cualquier navegador web.

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 siguiente comando:
./gradlew javadoc