Se encuentra en:
JAVADOC
RECU-0109 (Recurso Herramienta)
Tabla de contenidos
- Área: Reglas Generales de Construcción de Aplicaciones Java
- 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 . Es de gran utilidad para la comprensión del desarrollo. Por ello debemos de estandarizar su uso para facilitar la comprensión de forma global entre todos los desarrolladores.
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 /**..*/
- Es preferible el uso de la tercera persona en los comentarios, ya que la documentación suele estar destinada a un público amplio
- Se ubican siempre antes de los clases, métodos, interfaces y atributos a describir
- Un comentario JAVADOC esta compuesto de una definición seguida de un bloque de Tags relacionadas
A continuación se ofrece una tabla con las etiquetas principales que se usan en JAVADOC son 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 parametros |
| @see | Una referencia a otra clase o utilidad |
| @deprecated | El método ha sido reemplazado por otro |
Comentarios de clases
Antes de la declaración de la clase se introducirá un comentario de documentación que contenga la descripción de la clase y 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
Especificar descripción, parámetros, tipo de retorno, excepciones que se lanzan. Si es importante dentro del método la llamada a otro método, también se referenciará.
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
Se debe especificar su descripción, si procede, su modificador (private, public) y cuáles son los valores válidos o que pasa si su valor es null, en caso de restricciones por cualquiera de estas dos razones. Se debe evitar la declaración de varias variables en una misma línea.
Ejemplo:
/**
* Frase corta descriptiva
* Descripción de la variable.
* Valores válidos (si aplica)
* Comportamiento en caso de que sea null(si aplica)
*/
