viernes, 21 de enero de 2011

JAVADOC

JAVADOC: nos sirve para realizar comentarios, indicar el autor,la versión de la clase, método o incluso paquetes.


 Los comentarios JavaDoc están destinados a describir, principalmente, clases y métodos. Como están pensados para que otro programador los lea y utilice la clase (o método) correspondiente, se decidió fijar al menos parcialmente un formato común, de forma que los comentarios escritos por un programador resultaran legibles por otro. Para ello los comentarios JavaDoc deben incluir unos indicadores especiales, que comienzan siempre por '@' y se suelen colocar al comienzo de línea. Por ejemplo esta es una clase para representar números círculos (reducida al mínimo):

package figuras;

/**
 * Una clase para representar círculos situados sobre el plano.
 * Cada círculo queda determinado por su radio junto con las 
 * coordenadas de su  centro.
 * @version 1.2, 24/12/04
 * @author Rafa Caballero
 */

INDICADORES MAS USUALES

  • @author nombreDelAutor descripción. 
Indica quién escribió el código al que se refiere el comentario. Si son varias personas se escriben los nombres separados por comas o se repite el indicador, según se prefiera. Es normal incluir este indicador en el comentario de la clase y no repetirlo para cada método, a no ser que algún método haya sido escrito por otra persona. 
  •  @version númeroVersión descripción.
Si se quiere indicar la versión. Normalmente se usa para clases, pero en ocasiones también para métodos. 
  •  @param nombreParámetro descripción.
Para describir un parámetro de un método. 
  •  @return descripción.
Describe el valor de salida de un método. 
  •  @see nombre descripción
Cuando el trozo de código comentado se encuentra relacionada con otra clase o método, cuyo nombre se indica en nombre. 
  •  @throws nombreClaseExcepción descripción
Cuando un método puede lanzar una excepción ("romperse" si se da alguna circunstancia) se indica así. 
  •  @deprecated descripción.
 Indica que el método (es más raro encontrarlos para una clase) ya no se usa y se ha sustituido por otro. 


HERRAMIENTA JAVADOC


 Aparte de obtenerse comentarios más fáciles de leer para otros programadores debido al formato impuesto por los indicadores, la principal utilidad de estos comentarios es que pueden utilizarse para generar la documentación de los programas. Para ello se utiliza la herramienta javadoc parte de JDSK. El formato más sencillo de esta herramienta, cuando se emplea desde línea de comandos es:
javadoc fichero.java
Por ejemplo:
javadoc Círculo.java
Lo que hace esta herramienta es extraer los comentarios JavaDoc contenidos en el programa Java indicado y construir con ellos ficheros .html que puede servir como documentación de la clase. Por ejemplo, esta es el fichero Círculo.html que genera javadoc (entre otros) al procesar el fichero Círculo.java (para distinguirlo de este documento muestro el fondo en color, aunque en realidad es blanco): 

No hay comentarios:

Publicar un comentario