Hola a todos, hoy os explicare como utilizar Javadoc para documentar nuestras clases.
Javadoc es una utilidad incluida en el JDK, que genera documentación automática en formato HTML, a partir de código fuente Java.
Los comentarios deben ser escritos siguiendo una serie de reglas, donde podrán figurar las propias etiquetas Javadoc junto con etiquetas HTML. Un ejemplo de Javadoc es el API de Java.
Se documenta las clases, los métodos, constructores, paquetes y atributos. En principio, los atributos y métodos privados no es necesario documentarlos con Javadoc,
La sintaxis de Javadoc es:
/**
* Texto con alguna descripción (posibilidad de usar HTML)
*
* Etiquetas javadoc (comienzan por @)
*
*/
En las clases, se hace una breve descripción de la clase y se suele escribir una etiquetas de Javadoc especiales para las clases.
En los métodos y constructores, la primera frase describe lo que hace el método de forma breve, en las siguiente lineas definimos las etiquetas de Javadoc, ahora hablamos de ellas.
En los atributos, se escribe una breve definición del mismo.
Las etiquetas de Javadoc van precedidas por @, estos son los mas usados:
| Etiqueta | Descripción |
|---|---|
| @author | Autor de la clase. Solo para las clases. |
| @version | Versión de la clase. Solo para clases. |
| @see | Referencia a otra clase, ya sea del API, del mismo proyecto o de otro. Por ejemplo: @see cadena @see paquete.clase#miembro @see enlace |
| @param | Descripción parámetro. Una etiqueta por cada parámetro. |
| @return | Descripción de lo que devuelve. Solo si no es void. Podrá describir valores de retorno especiales según las condiciones que se den, dependiendo del tipo de dato |
| @throws | Descripción de la excepción que puede propagar. Habrá una etiqueta throws por cada tipo de excepción. |
| @deprecated | Marca el método como obsoleto. Solo se mantiene por compatibilidad. |
| @since | Indica el nº de versión desde la que existe el método. |
Veamos un ejemplo:
/**
* Clase Empleado
*
* Contiene informacion de cada empleado
*
* @author Fernando
* @version 1.0
*/
public class Empleado {
//Atributos
/**
* Nombre del empleado
*/
private String nombre;
/**
* Apellido del empleado
*/
private String apellido;
/**
* Edad del empleado
*/
private int edad;
/**
* Salario del empleado
*/
private double salario;
//Metodos publicos
/**
* Suma un plus al salario del empleado si el empleado tiene mas de 40 años
* @param sueldoPlus
* @return <ul>
* <li>true: se suma el plus al sueldo</li>
* <li>false: no se suma el plus al sueldo</li>
* </ul>
*/
public boolean plus (double sueldoPlus){
boolean aumento=false;
if (edad>40 && compruebaNombre()){
salario+=sueldoPlus;
aumento=true;
}
return aumento;
}
//Metodos privados
/**
* Comprueba que el nombre no este vacio
* @return <ul>
* <li>true: el nombre es una cadena vacia</li>
* <li>false: el nombre no es una cadena vacia</li>
* </ul>
*/
private boolean compruebaNombre(){
if(nombre.equals("")){
return false;
}
return true;
}
//Constructores
/**
* Constructor por defecto
*/
public Empleado(){
this ("", "", 0, 0);
}
/**
* Constructor con 4 parametros
* @param nombre nombre del empleado
* @param apellido nombre del empleado
* @param edad edad del empleado
* @param salario salario del empleado
*/
public Empleado(String nombre, String apellido, int edad, double salario){
this.nombre=nombre;
this.apellido=apellido;
this.edad=edad;
this.salario=salario;
}
}
Espero que os sea de ayuda. Si tenéis dudas, preguntad. Estamos para ayudarte.
Muy interesante el post amigo, el HTML es un gran desconocido.
TRAFFIC CLUB, Fútbol y Tenis, más que un juego
EXCELENTE AMIGO!!… Poco conocía yo del JavaDoc, gran aporte, estimado.