Documentación
Java dispone de un sistema de documentación oficial llamado Javadoc. Permite escribir comentarios especiales directamente en el código fuente que, posteriormente, pueden convertirse automáticamente en documentación HTML navegable (similar a la documentación oficial de Java que encontrarás en cualquier IDE o en la web de Oracle).
Un comentario Javadoc se distingue de un comentario normal porque comienza con /** y termina con */:
// Comentario normal — no forma parte de la documentación
/* Comentario de bloque — tampoco */
/**
* Comentario Javadoc — SÍ forma parte de la documentación
*/
En Visual Studio Code, si en la línea antes de la definición de un método escribimos /** y pulsamos Enter, se generará la estructura de la documentación y solo deberemos escribir la información necesaria. También funciona en IntelliJ IDEA.
Estructura de un comentario Javadoc
Un bloque Javadoc tiene dos partes:
- Descripción: texto libre que explica el propósito del elemento documentado.
- Etiquetas (tags): marcadores que comienzan por
@y aportan información estructurada (parámetros, valor de retorno, excepciones, etc.).
/**
* Descripción breve en la primera línea.
*
* Descripción más detallada a continuación, si es necesario.
* Puede ocupar varios párrafos.
*
* @tag1 descripción del tag
* @tag2 descripción del tag
*/
Documentar una clase
El comentario Javadoc de una clase se coloca justo antes de su declaración y debe explicar:
- Qué representa o qué responsabilidad tiene la clase.
- Cualquier consideración de uso relevante.
Las etiquetas más habituales a nivel de clase son:
| Etiqueta | Descripción |
|---|---|
@author | Nombre del autor o autores de la clase |
@version | Versión actual de la clase |
@since | Versión del proyecto desde la que existe esta clase |
@see | Referencia a otra clase o método relacionado |
Ejemplo:
/**
* Representa una cuenta bancaria con operaciones básicas de ingreso y retirada.
*
* Esta clase gestiona el saldo de un titular y registra cada movimiento
* realizado. No permite saldos negativos en ningún momento.
*
* @author Ana García
* @version 1.2
* @since 1.0
* @see Titular
* @see Movimiento
*/
public class CuentaBancaria {
// ...
}
Documentar un constructor
El constructor se documenta explicando qué hace al crear el objeto y describiendo cada parámetro que recibe. Las etiquetas habituales son:
| Etiqueta | Descripción |
|---|---|
@param | Describe un parámetro: su nombre y qué representa |
@throws | Indica qué excepción puede lanzar y bajo qué condición |
Ejemplo:
/**
* Crea una nueva cuenta bancaria con un titular y un saldo inicial.
*
* @param titular nombre completo del propietario de la cuenta
* @param saldo importe inicial depositado; debe ser mayor o igual a 0
* @throws IllegalArgumentException si el saldo inicial es negativo
*/
public CuentaBancaria(String titular, double saldo) {
if (saldo < 0) {
throw new IllegalArgumentException("El saldo inicial no puede ser negativo.");
}
this.titular = titular;
this.saldo = saldo;
}
Documentar un método
Es la parte más habitual y detallada de Javadoc. Además de la descripción y @param, se añade la etiqueta @return para describir el valor devuelto.
| Etiqueta | Descripción |
|---|---|
@param | Describe cada parámetro de entrada |
@return | Describe el valor que devuelve el método |
@throws | Indica qué excepción puede lanzarse y cuándo |
@see | Referencia a otro método o clase relacionada |
@deprecated | Marca el método como obsoleto e indica qué usar en su lugar |
Ejemplo (método con valor de retorno):
/**
* Ingresa una cantidad de dinero en la cuenta.
*
* El saldo se incrementa con el importe indicado y el movimiento
* queda registrado en el historial de la cuenta.
*
* @param importe cantidad a ingresar; debe ser estrictamente positiva
* @return el nuevo saldo tras el ingreso
* @throws IllegalArgumentException si el importe es cero o negativo
*/
public double ingresar(double importe) {
if (importe <= 0) {
throw new IllegalArgumentException("El importe debe ser positivo.");
}
saldo += importe;
return saldo;
}
Ejemplo (método que devuelve void):
Cuando el método no devuelve nada, simplemente se omite la etiqueta @return.
/**
* Muestra por consola el saldo actual y el nombre del titular.
*/
public void mostrarResumen() {
System.out.println("Titular: " + titular);
System.out.println("Saldo: " + saldo + " €");
}
Ejemplo (método con excepción documentada):
/**
* Retira una cantidad de dinero de la cuenta.
*
* @param importe cantidad a retirar; debe ser positiva y no superar el saldo disponible
* @return el saldo restante tras la operación
* @throws IllegalArgumentException si el importe es cero o negativo
* @throws IllegalStateException si el importe supera el saldo disponible
*/
public double retirar(double importe) {
if (importe <= 0) {
throw new IllegalArgumentException("El importe debe ser positivo.");
}
if (importe > saldo) {
throw new IllegalStateException("Saldo insuficiente.");
}
saldo -= importe;
return saldo;
}
Ejemplo completo
/**
* Representa una cuenta bancaria con operaciones básicas de ingreso y retirada.
*
* No permite saldos negativos en ningún momento.
*
* @author Ana García
* @version 1.2
* @since 1.0
*/
public class CuentaBancaria {
private String titular;
private double saldo;
/**
* Crea una nueva cuenta bancaria con un titular y un saldo inicial.
*
* @param titular nombre completo del propietario de la cuenta
* @param saldo importe inicial; debe ser mayor o igual a 0
* @throws IllegalArgumentException si el saldo inicial es negativo
*/
public CuentaBancaria(String titular, double saldo) {
if (saldo < 0) {
throw new IllegalArgumentException("El saldo inicial no puede ser negativo.");
}
this.titular = titular;
this.saldo = saldo;
}
/**
* Ingresa una cantidad de dinero en la cuenta.
*
* @param importe cantidad a ingresar; debe ser estrictamente positiva
* @return el nuevo saldo tras el ingreso
* @throws IllegalArgumentException si el importe es cero o negativo
*/
public double ingresar(double importe) {
if (importe <= 0) {
throw new IllegalArgumentException("El importe debe ser positivo.");
}
saldo += importe;
return saldo;
}
/**
* Retira una cantidad de dinero de la cuenta.
*
* @param importe cantidad a retirar; debe ser positiva y no superar el saldo disponible
* @return el saldo restante tras la operación
* @throws IllegalArgumentException si el importe es cero o negativo
* @throws IllegalStateException si el importe supera el saldo disponible
*/
public double retirar(double importe) {
if (importe <= 0) {
throw new IllegalArgumentException("El importe debe ser positivo.");
}
if (importe > saldo) {
throw new IllegalStateException("Saldo insuficiente.");
}
saldo -= importe;
return saldo;
}
/**
* Devuelve el saldo actual de la cuenta.
*
* @return saldo disponible en la cuenta
*/
public double getSaldo() {
return saldo;
}
/**
* Devuelve el nombre del titular de la cuenta.
*
* @return nombre completo del titular
*/
public String getTitular() {
return titular;
}
}
Generación de la documentación HTML
Desde la terminal, el comando javadoc genera la documentación en HTML a partir de los comentarios del código:
javadoc -d docs/ src/CuentaBancaria.java
Esto crea una carpeta docs/ con la documentación navegable en HTML, equivalente a la documentación oficial de Java.
La mayoría de IDEs (IntelliJ IDEA, Eclipse, VS Code) también permiten generar Javadoc desde su interfaz gráfica y muestran los comentarios Javadoc al pasar el cursor sobre una clase o método.