Documentar con Javadoc

Un programa bien desarrollado y con buenas prácticas incluye indefectiblemente, por convención, ser documentado de forma correcta.

La documentación de un programa se realiza para permitir a otros programadores comprender rápidamente de qué va un desarrollo, cuál es su finalidad, y como está constituido, sus atributos, clases, métodos, parámetros, retornos e interfaces.

Java nos ofrece un instrumento desarrollado por Oracle que conocemos como Javadoc, el cual nos permite de manera ágil, documentar nuestra API.

¿Qué es Javadoc?

Es una herramienta incluida en el SDK (Kit de desarrollo de software) que los programadores empleamos para explicar la utilidad y composición de nuestro programa.

Construimos esta información con palabras reservadas orientadas a generar documentación técnica, precedidas de un tag (@) y que se escriben entre /**      */.    

Por ejemplo:

/** @return: documenta el valor de retorno de un método */

Con la información que suministramos dentro de estas barras y asteriscos, Java generará de forma automática un archivo en formato HTML a partir de nuestro código fuente, al que podremos acceder como si de una página web se tratara.

Proceso de documentación de nuestro programa en Java

Los comentarios, como ya dijimos los ponemos entre /** y */, deben ir precedidos de un caracter @ (sin el @ Java no comprenderá que es documentación y lo interpretará como un comentario común), seguido del nombre del tag que identifica que tipo de elemento estamos documentando. Se pueden combinar varias etiquetas (tags).

Con esta herramienta podemos registrar el comportamiento de clases, métodos, interfaces, parámetros y retornos, entre otros.

Se colocan al inicio y por encima del código de una clase, un atributo, un método o porción de código que queremos documentar.

Cada elemento documentado deberá incluir una breve descripción, funcionalidad y objetivo, como así también sus parámetros y retornos. 

También debemos incluir, autor, número de versión y fecha de creación.

Ejemplo de documentación en Javadoc

/**
 * @author pepito
 * fecha creación 25/10
 * @param número Recibe el número para factorizar
 * @return devuelve el factorial de un número dado
 */
public static int factorialNR(int numero) {
    int temp;
    int resultado = 1;

    for (temp = 1; temp <= numero; temp++) {
        resultado = resultado * temp;
    }
    return resultado;

}

Palabras reservadas para documentar en Java más utilizadas

• @author: Indica el/los autor/res de la clase o método.
• {@link}: Otorgamos un enlace a otra sección de la documentación, método o clase.
• @param: Documenta un parámetro de un método.
• @return: Documenta lo que retorna un método.
• @deprecated: Indica que el elemento utilizado es obsoleto y que no se recomienda su uso.
• @see: Informamos un enlace con documentación adicional.
• @version: Número de versión del método o clase.
• @throw: Indica que tipo de excepción lanza el método.

Algunas etiquetas son de uso específico para un tipo de código, por ejemplo @author y @version son para documentar clases e interfaces.

Con la etiqueta @param documentamos constructores y métodos. 

La etiqueta @return se usa para documentar métodos de tipo función.

Recordemos que siempre es fundamental documentar nuestro programa correctamente.

Junto al Javadoc, es buena recomendación incluir un archivo Leeme o Readme.

Otras consideraciones para la documentación en Java

• Según donde incluyamos el comentario para documentar, Javadoc sabrá definir que tipo de elemento estamos comentando.
• Para crear el documento y que sea reconocido como documentación, debemos emplear tags precedidas de un @ y dentro de la barra con asteriscos de apertura y cierre, incluir nuestros comentarios, si no hay aunque sea una sola línea que contenga @, el lenguaje lo tomará como un comentario local y no lo documentará.