Con el fin de facilitar la compresión de uso de una clase y sus métodos, éstos deben estar debidamente documentados informando de su funcionamiento, de los parámetros que se deben utilizar y de los resultados que se obtienen.

Para facilitar esta tarea, Java dispone de la herramienta javadoc, que genera una documentación estandarizada obteniéndose en formato web, semejante a la API oficial de Java.

Se debe seguir un modelo concreto para que se genere la documentación de forma correcta:

• Todos los comentarios deben comenzar por /** y terminar con */

• Se debe documentar la clase y cada método público (public), escribiendo un comentario delante de cada uno de ellos.

• Dentro del comentario se pueden utilizar etiquetas HTML.

• El comentario comenzará con una descripción general del objetivo de la clase y de los métodos.

• Después se pueden indicar una serie de valores utilizando unas etiquetas predefinidas, siendo las más importantes las siguientes:

  • @author: Para indicar el nombre del autor de la clase o método.

  • @version: Permite especificar la versión de la clase o método.

  • @param: Descripción de cada parámetro del método.

  • @return: Descripción del valor que retorna el método.

  • @throws: Excepción que puede lanzar el método.

/**
 * Aquí se debe escribir una descripción general del funcionamiento de la clase
 *
 * @author nombre del autor
 * @version 1.0
 */
public class ClaseEjemploJavadoc {
 
    /** atributo1 sirve para lo que sea */
    public String atributo1;
    private int atributo2;
 
    /**
     * Descripción del método constructor
     *
     * @param atributo1 Descripción del primer parámetro
     * @param atributo2 Descripción del segundo parámetro
     */
    ClaseEjemploJavadoc(String atributo1, int atributo2) {
        this.atributo1 = atributo1;
        this.atributo2 = atributo2;
    }
 
    /**
     * Descripción del método método1
     *
     * @param parámetro3 Descripción del valor que debe pasarse como parámetro
     * @return Descripción del valor que retorna el método al ser llamado
     */
    public int método1(int parámetro) {
        return 1;
    }
}

El entorno NetBeans proporciona una forma sencilla de generar la documentación en formato HTML a través de javadoc. Para ello se puede utilizar el menú Ejecutar > Generar Javadoc, o desde el menú contextual del proyecto.

Al generar la documentación se abre la página web que la contiene, que tendrá el siguiente estilo:

Para comprobar si se ha incluido toda la información necesaria o para facilitar la inclusión de los comentarios, NetBeans ofrece la herramienta Analizador Javadoc: Herramientas > Analizar Javadoc, que abre una ventana informando de la información que falta y la posibilidad de solucionar los problemas encontrados.