Javadoc

A continuación definimos una serie de reglas elementales:

• Los comentarios de JAVADOC se generan desde el código fuente y, por lo tanto, hay que incluir en el mismo etiquetas especiales para poder interpretarlas en la generación. La etiqueta que determina un comentario JAVADOC es /**..*/
• Un comentario JAVADOC está compuesto de una definición seguida de un bloque de etiquetas relacionadas

A continuación se ofrece una tabla con las etiquetas principales que se usan en JAVADOC con su descripción funcional:

Comentarios de clases

A continuación se presenta un ejemplo que muestra cómo se indican, en los comentarios de una clase, la descripción, el autor, la versión y la fecha.

Ejemplo:

/**
* Frase corta descriptiva
* Descripción de la clase
* @author Nombre Apellido / Empresa
* @version 0.1, 2004/05/30
*/

Comentarios de Métodos

Podemos ver cómo se incluyen los comentarios de los métodos en el siguiente ejemplo.  En él vemos la manera de especificar la descripción, los parámetros, el tipo de retorno y las excepciones que se lanzan. También vemos cómo se referenciaría la llamada a otro método.

Ejemplo:

/**
* Frase corta descriptiva
* Descripción del método.
* Mención al uso{@link es.loquesea.$app.util.Otra#unMetodo unMetodo}.
* @param param1 descripción del parámetro.
* @return qué devuelve el método.
* @exception tipo de excepción que lanza el método y en qué caso
* @see paquete.Clase#metodo Código al que se hace referencia
* @throws IllegalArgumentException el param1 no tiene el formato deseado
*/

Comentarios de Variables

La manera de incluir los comentarios a las variables es la que se muestra a continuación. En ella podemos ver cómo se especifican su descripción, su modificador (private, public), si procede, y cuáles son los valores válidos o qué ocurre si su valor es null.

Ejemplo:

/**
* Frase corta descriptiva
* Descripción de la variable.
* Valores válidos (si aplica)
* Comportamiento en caso de que sea null(si aplica)
*/