Javadoc
Javadoc Es una utilidad de Sun Microsystems para generar APIs en formato HTML de un documento de código fuente Java.
Javadoc es el estándar de la industria para documentar clases de Java. La mayoría de los IDEs los generan automáticamente.
Etiquetas Javadoc
Para generar APIs con Javadoc han de usarse etiquetas (tag's) de HTML o ciertas palabras reservadas precedidas por el carácter "@".
Estas etiquetas se escriben al principio de cada clase, miembro o método, dependiendo de qué objeto se desee describir, mediante un comentario iniciado con "/**" y acabado con "*/".
A continuación explicamos algunas de las palabras reservadas:
Nota 1: En uso explica lo que se pone tras el tag.
Nota 2: Versión indica desde qué versión de Javadoc es válida.
Tag Descripción Uso Versión @author Nombre del desarollador. nombre_autor 1.0 @deprecated Indica que la función o clase es antigua y que no se recomienda su uso porque posiblemente desaparecerá en versiones posteriores. descripción 1.0 @param Definición de un parámetro de una función, es requerido para todos los parámetros de la función. nombre_parametro descripción 1.0 @return Informa de lo que devuelve la función, no se puede usar en construcctores o métodos "void". descripción 1.0 @see Asocia con otro método o clase. referencia (#función(); clase#función(); paquete#clase; paquete.clase#función()). 1.0 @throws Excepción lanzada por el método nobre_clase descripción 1.2 @version Versión del método o clase. versión 1.0
Ejemplo
Un ejemplo de un Javadoc de una función.
/**
* Inserta un título en la clase descripción.
* Al ser el título obligatorio, si es nulo o vacío se lanzará
* una excepción.
* @author Victor. Ant. Torre
* @param titulo El nuevo título de la descripción.
* @throws Exception Si titulo es null, está vacío o contiene solo espacios.
*/
public void setTitulo (String titulo) throws Exception
{
if (titulo == null || titulo.trim().equals(""))
{
throw new Exception ("El título no puede ser nulo o vacío");
}
else
{
this.titulo = titulo;
}
}