JavaDoc - Documentación de Clases

Javadoc es una utilidad incluida en el Kit de Desarrollo de Java (JDK) para la generación de documentación de APIs en formato HTML a partir de código fuente Java. La aplicación javadoc se encuentra en la carpeta bin del directorio del JDK de Java, junto a otros programas como java, javac, jar, etc.

Javadoc es el estándar para documentar clases de Java. La mayoría de los IDEs para Java utilizan javadoc para generar de forma automática documentación de clases.

Veamos en primer lugar qué se debe incluir al documentar una clase:

• Nombre de la clase, descripción general, número de versión, nombre de autores.
• Documentación de cada constructor o método (especialmente los públicos) incluyendo:
  • nombre del constructor o método, descripción general, tipo de retorno, nombres y tipos de parámetros si los hay, descripción de parámetros (si los hay), descripción del valor que devuelve.
• Las variables de instancia o de clase no se suelen documentar a nivel de javadoc. Solo las constantes públicas, si hubiera.

Es muy útil fijarse en el formato que tiene la documentación de métodos y constructores ya existentes en la API de Java. Basta con situar el cursor del ratón encima de algún método o constructor.

• La documentación para javadoc ha de incluirse entre símbolos de comentario que han de empezar con una barra y doble asterisco, y terminar con un asterisco y barra simple.

/**
 *    Esto es un comentario para javadoc 
 */

• La ubicación del comentario le define a javadoc qué representa el comentario:
  • si está incluido justo antes de la declaración de clase se considerará un comentario de clase,
  • si está incluido justo antes de la signatura de un constructor o método se considerará un comentario de ese constructor o método.
  • lo mismo en caso de una constante de clase.

• Para alimentar javadoc se usan ciertas palabras reservadas (tags) precedidas por el carácter “@”, dentro de los símbolos de comentario javadoc. Si no existe al menos una línea que comience con @ no se reconocerá el comentario para la documentación de la clase.

Si nos fijamos en la API de Java de alguna clase, p.e String podemos tener una idea de cómo y qué se debe documentar.

Aquí vemos la documentación del método charAt() de la clase String:

/**
 * Returns the {@code char} value at the
 * specified index. An index ranges from {@code 0} to
 * {@code length() - 1}. The first {@code char} value of the sequence
 * is at index {@code 0}, the next at index {@code 1},
 * and so on, as for array indexing.
 *
 * <p>If the {@code char} value specified by the index is a
 * <a href="Character.html#unicode">surrogate</a>, the surrogate
 * value is returned.
 *
 * @param      index   the index of the {@code char} value.
 * @return     the {@code char} value at the specified index of this string.
 *             The first {@code char} value is at index {@code 0}.
 * @exception  IndexOutOfBoundsException  if the {@code index}
 *             argument is negative or not less than the length of this
 *             string.
 */
 public char charAt(int index) {
    if ((index < 0) || (index >= value.length)) {
            throw new StringIndexOutOfBoundsException(index);
    }
    return value[index];
 }

Como vemos se indica una descripción del funcionamiento del método, qué representa cada parámetro, qué se espera devolver y si lanza alguna excepcion.

A continuación se muestra como aparece en los documentos Javadoc generados:

Y aquí como se ve cuando accedo a la documentación del método en Eclipse:

Como se ha indicado anteriormente, en la documentación de un método se debe indicar:

• Descripción de la funcionalidad del método
• Descripción de la finalidad de los parámetros
• Descripción de la finalidad del valor de retorno
• Excepciones, si es que lanza alguna

• Documentación de clases e interfaces

En el comentario de cada clase o interface se debe explicar para que sirve esa clase o interface.

Deben usarse al menos las etiquetas:

• @author
• @version
• @since

• Documentación de constructores y métodos

En el comentario de cada método/constructor se debe explicar para que sirve.

Deben usarse al menos las etiquetas:

• @param: una por argumento de entrada, indicando el tipo, y su funcionalidad
• @return: indicando el tipo y su funcionalidad, si el método no es void
• @exception ó @throws: una por tipo de Exception que se puede lanzar, solo si se lanzan (@exception y @throws se pueden usar indistintamente).

Selecionamos el proyecto del que necesitamos obtener el Javadoc y vamos a Project → Generate Javadoc

• Si el campo de Javadoc command está vacío indicamos la ruta de nuestro javadoc.exe (En este caso puntual C:\Program Files\Java\jdk***\bin\javadoc.exe).
• Luego indicamos la carpeta de destino y seguimos el asistente.

• Por defecto usaremos la ubicación estándar, que siempre es en nuestra carpeta base del proyecto que contiene las clases que queremos documentar, en un nuevo directorio llamado doc.

• Al pulsar finalizar, se habrá generado un directorio doc en la ruta específicada.
• Si abrimos el fichero index.html accederemos a la documentación de nuestro proyecto.

JavaDoc es una aplicación que viene en el paquete JDK de Java, debemos tener ese paquete para poder usarlo y seleccionaremos el programa Javadoc.exe contenido en la carpeta bin (binarios) de la carpeta de nuestro jdk. Normalmente en “Archivos de programa /Java”

© 2024 Fernando Valdeón