Javadoc

De Wikipedia, la enciclopedia libre

Javadoc es una utilidad de Sun Microsystems para la generación de documentación de APIs en formato HTML a partir 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.

[editar] Etiquetas Javadoc

Para generar APIs con Javadoc han de usarse etiquetas (tag's) de HTML o ciertas palabras reservadas precedidas por el caracter "@".
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 se explican algunas de las palabras reservadas - puede verse una lista completa de las tags con su correpondiente uso en sun.com

Nota 1: En uso explica la semántica del texto 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 desarrollador.	nombre_autor	1.0
@deprecated	Indica que el método 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 un método, es requerido para todos los parámetros del método.	nombre_parametro descripción	1.0
@return	Informa de lo que devuelve el método, no se puede usar en constructores o métodos "void".	descripción	1.0
@see	Asocia con otro método o clase.	referencia (#método(); clase#método(); paquete.clase; paquete.clase#método()).	1.0
@throws	Excepción lanzada por el método	nombre_clase descripción	1.2
@version	Versión del método o clase.	versión	1.0

[editar] Ejemplo

Un ejemplo de un Javadoc de un método.

/**
 * 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.
 *
 * @param titulo El nuevo título de la descripción.
 * @throws IllegalArgumentException Si titulo es null, está vacío o contiene solo espacios.
 */
public void setTitulo (String titulo) throws IllegalArgumentException
{
  if (titulo == null || titulo.trim().equals(""))
  {
      throw new Exception ("El título no puede ser nulo o vacío");
  }
  else
  {
      this.titulo = titulo;
  }
}

[editar] Enlaces externos

• Página principal de Javadoc - incluye enlaces a documentacion de referencia y a tutoriales
• Documentacion de uso de Javadoc - describe la herramienta javadoc e incluye ejemplos de uso y etiquetas válidas para Windows
• Buscador de Javadocs online - permite encontrar la documentación Javadoc de una clase a partir de su nombre