Comentarios de documentación en Java: Dominando Javadoc y tipos de comentarios

El lenguaje Java soporta tres tipos de comentarios:

Este capítulo explica Javadoc y cómo usarlo para generar documentación útil para código Java.

¿Qué es Javadoc?

Javadoc es una herramienta que viene con el JDK y se usa para generar documentación de código Java en formato HTML a partir del código fuente, que requiere documentación en un formato predefinido.

Ejemplo simple donde las líneas dentro de /*….*/ son comentarios multilínea de Java. La línea precedida por // es comentario de una línea.

Ejemplo

/**
 * El programa HelloWorld implementa una aplicación que
 * simplemente muestra "¡Hola Mundo!" en la salida estándar.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        // Imprime ¡Hola, Mundo! en la salida estándar.
        System.out.println("¡Hola Mundo!");
    }
}

Puedes incluir etiquetas HTML requeridas dentro de la descripción. Por ejemplo, <h1>....</h1> para encabezado y <p> para salto de párrafo:

Ejemplo

/**
 * <h1>¡Hola, Mundo!</h1>
 * El programa HelloWorld implementa una aplicación que
 * simplemente muestra "¡Hola Mundo!" en la salida estándar.
 * <p>
 * Dar comentarios adecuados en tu programa lo hace más
 * amigable y se asume como código de alta calidad.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("¡Hola Mundo!");
    }
}

Etiquetas de Javadoc

La herramienta javadoc reconoce las siguientes etiquetas:

Ejemplo

El siguiente programa usa algunas etiquetas importantes. Puedes usar otras según tus necesidades.

La documentación sobre la clase AddNum se producirá en HTML AddNum.html y también se creará un archivo maestro index.html.

import java.io.*;
/**
 * <h1>¡Sumar Dos Números!</h1>
 * El programa AddNum implementa una aplicación que
 * simplemente suma dos números enteros dados e imprime
 * el resultado en pantalla.
 * <p>
 * <b>Nota:</b> Dar comentarios adecuados en tu programa lo hace más
 * amigable y se asume como código de alta calidad.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class AddNum {
    /**
     * Este método suma dos enteros. Es la forma más simple
     * de un método de clase, solo para mostrar el uso de
     * varias etiquetas javadoc.
     * @param numA Primer parámetro para addNum
     * @param numB Segundo parámetro para addNum
     * @return int Retorna la suma de numA y numB.
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }
    /**
     * Método principal que usa addNum.
     * @param args No usado.
     * @return Nada.
     * @exception IOException En error de entrada.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("Suma de 10 y 20 es: " + sum);
    }
}

Procesa el archivo AddNum.java con javadoc:

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning

Puedes ver la documentación generada en AddNum. Si usas JDK 1.7, javadoc no genera un gran stylesheet.css; sugerimos descargar y usar el estándar desde https://docs.oracle.com/javase/7/docs/api/stylesheet.css