Javadoc y documentación

Un proyecto puede compilar y aun así resultar difícil de usar. Si otra persona no sabe qué recibe un método, qué devuelve o cómo ejecutar el proyecto, tendrá que deducirlo leyendo todo el código.

La documentación útil reduce esa incertidumbre. En esta unidad distinguiremos tres piezas complementarias:

• los comentarios internos explican una decisión poco evidente;
• Javadoc describe cómo usar una API;
• el README.md explica cómo preparar, comprobar y ejecutar el proyecto.

Comentarios que aportan contexto

Un comentario no debe traducir literalmente el código:

contador++; // Incrementa contador en uno

Es más útil explicar el motivo de una decisión:

// Conservamos el orden de inserción para mostrar las tareas como se crearon.
Map<Long, Tarea> tareas = new LinkedHashMap<>();

Antes de comentar, comprueba si un nombre más claro elimina la necesidad. Los comentarios desactualizados son peores que su ausencia porque describen un comportamiento que ya no existe.

Documentar una API con Javadoc

Javadoc usa bloques /** ... */ colocados antes de clases, constructores y métodos. Su objetivo es describir el contrato observable, no los pasos internos.

package es.skilly.tareas;

/**
 * Representa una tarea identificada dentro del gestor.
 */
public class Tarea {
    private final long id;
    private final String descripcion;

    /**
     * Crea una tarea pendiente.
     *
     * @param id identificador positivo de la tarea
     * @param descripcion texto que se mostrará al usuario
     * @throws IllegalArgumentException si el identificador no es positivo
     *         o la descripción está vacía
     */
    public Tarea(long id, String descripcion) {
        if (id <= 0) {
            throw new IllegalArgumentException("El id debe ser positivo");
        }
        if (descripcion == null || descripcion.isBlank()) {
            throw new IllegalArgumentException("La descripción es obligatoria");
        }
        this.id = id;
        this.descripcion = descripcion;
    }

    /**
     * Devuelve el identificador estable de la tarea.
     *
     * @return identificador positivo
     */
    public long getId() {
        return id;
    }

    /**
     * Devuelve la descripción visible.
     *
     * @return descripción no vacía
     */
    public String getDescripcion() {
        return descripcion;
    }
}

Los tags más frecuentes son:

• @param nombre: significado y restricciones de un parámetro;
• @return: significado del resultado, no solo su tipo;
• @throws Tipo: condición que provoca una excepción;
• @see: referencia relacionada cuando aporta una ruta útil.

No añadas @return a un método void ni documentes excepciones que el método no puede producir. Si cambia el contrato, actualiza código, pruebas y documentación juntos.

Qué merece documentarse

Prioriza la API que otras partes del proyecto necesitan usar:

/**
 * Busca una tarea por su identificador.
 *
 * @param id identificador buscado
 * @return la tarea encontrada
 * @throws java.util.NoSuchElementException si el id no existe
 * @see Tarea#getId()
 */
public Tarea buscar(long id) {
    // implementación
}

Evita texto que solo repita la firma, como «método que busca». Explica condiciones, resultado y casos de error. Los métodos privados solo necesitan documentación cuando su decisión interna no queda clara mediante el código y sus nombres.

Generar la documentación con Maven

Fijamos la versión del plugin para obtener el mismo proceso en distintos equipos:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.11.2</version>
        </plugin>
    </plugins>
</build>

Desde la raíz, donde está pom.xml:

mvn javadoc:javadoc

El sitio generado queda en target/reports/apidocs/. Abre index.html y comprueba que aparecen el paquete, la clase, los métodos y sus contratos. target/ sigue siendo un resultado regenerable y no se versiona.

Si Javadoc avisa de un tag incorrecto o una referencia rota, corrige la fuente y vuelve a generar. No edites el HTML resultante.

El README completa el recorrido

Javadoc responde cómo se usa el código. Un README.md breve responde cómo se trabaja con el proyecto:

# Gestor de tareas

Requiere Java 17 y Maven 3.9 o compatible.

## Comprobar el proyecto

```bash
mvn clean verify
```

## Generar Javadoc

```bash
mvn javadoc:javadoc
```

Incluye requisitos reales, comandos copiables y cualquier decisión necesaria para reproducir el resultado. No prometas pasos que no hayas probado.

Práctica: documentar un servicio

Documenta este contrato y genera su Javadoc:

public double calcularMedia(List<Integer> notas) {
    if (notas == null || notas.isEmpty()) {
        throw new IllegalArgumentException("Se necesita al menos una nota");
    }
    return notas.stream()
        .mapToInt(Integer::intValue)
        .average()
        .orElseThrow();
}

Tu documentación debe indicar qué representa notas, qué devuelve el método y cuándo falla.

Solución

/**
 * Calcula la media aritmética de un conjunto de notas.
 *
 * @param notas notas que participan en el cálculo
 * @return media aritmética de las notas
 * @throws IllegalArgumentException si la lista es nula o está vacía
 */
public double calcularMedia(List<Integer> notas) {
    if (notas == null || notas.isEmpty()) {
        throw new IllegalArgumentException("Se necesita al menos una nota");
    }
    return notas.stream()
        .mapToInt(Integer::intValue)
        .average()
        .orElseThrow();
}

La solución explica el contrato sin narrar el stream. Tras ejecutar mvn javadoc:javadoc, comprueba visualmente que los tres tags aparecen asociados al método.

Errores habituales

• Documentar cada línea y ocultar así las decisiones importantes.
• Copiar una descripción antigua después de cambiar el comportamiento.
• Escribir un @param cuyo nombre no coincide con la firma.
• Versionar target/reports/apidocs en lugar de regenerarlo.
• Mantener comandos de README que nunca se han ejecutado.

Ya podemos estructurar, construir, probar, diagnosticar, registrar y documentar un proyecto. En la siguiente unidad practicaremos ese recorrido completo sobre código que necesita mejorar.