- Área: Especificaciones de Codificación y Construcción
- Carácter del recurso: Recomendado
Descripción
JAVADOC, es una herramienta del SDK que permite documentar, de una manera rápida y sencilla, las clases y métodos que se proveen, siendo de gran utilidad para la comprensión del desarrollo.
Uso en MADEJA
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:
Etiqueta | Descripción |
---|---|
@author | Autor del elemento a documentar |
@version | Versión del elemento de la clase |
@return | Indica los parámetros de salida |
@exception | Indica la excepción que puede generar |
@param | Código para documentar cada uno de los parámetros |
@see | Una referencia a otra clase o utilidad |
@deprecated | El método ha sido reemplazado por otro |
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)
*/
Enlaces externos
Pautas
Código | Título | Tipo | Carácter | |
---|---|---|---|---|
LIBP-0015 | Convenio de codificación específico para Java | Libro de pautas | Directriz | Obligatoria |