Introduccin JavaDoc

JavaDoc es una herramienta integrada al SDK de Java, que permite documentar de manera rpida y sencilla las clases y los mtodos que se proveen. JavaDoc es un programa que se ejecuta simplemente con: javadoc [paquete] archivo.java, ... La documentacin se genera del archivo fuente, por lo que es necesario utilizar los comentarios especiales para JavaDoc: /** * Esto significa documentaci\'on para JavaDoc */ public class Documentacion { ... Dado que los smbolos /** son ignorados por el compilador, cuando se ejecuta JavaDoc estos adquieren significado de documentacin. La documentacin sigue la regla de que todo lo que va anterior a un mtodo es la descripcin de ese mtodo, as por ejemplo: /** * La clase ejemplo, hace uso de las facilidades de JavaDoc */ public class Ejemplo { /** * Constructor principal, inicializa los componentes a utilizar * en el objeto. */ public Ejemplo() { } } Adems, JavaDoc provee de ciertas palabras que permiten ayudar a la documentacin de los mtodos. Ejemplo: /** * Thrown to indicate that the application has attempted to convert * a string to one of the numeric types, but that the string does not * have the appropriate format. * * @author unascribed * @version 1.16, 02/02/00 * @see java.lang.Integer#toString() * @since JDK1.0 */ public class NumberFormatException extends IllegalArgumentException { /** * Constructs a <code>NumberFormatException</code> with no detail message. */ public NumberFormatException () { super(); } /** * Constructs a <code>NumberFormatException</code> with the * specified detail message.

* * @param s the detail message. */ public NumberFormatException (String s) { super (s); }

La anterior es un ejemplo tomado de las fuentes de Java, que es la clase NumberFormatException, vemos por ejemplo que una palabra clave empieza con @ y despus un identificador, los identificadores son: Palabra reservada Versin Descripcin @author @deprecated @exception @param @return @see @since @throws 1.0 1.0 1.0 1.0 1.0 1.0 1.1 1.2 El autor del mtodo, clase. El mtodo ha sido reemplazado por otro. La excepcin que puede generar. Despus viene el parmetro, esto se hace para documentar todos los parmetros que requiere el mtodo. El valor que regresa Una referencia a otra clase o mtodo de utilidad La versin desde que se incluye. Es un sinnimo para @exception.

@version 1.0 La versin del mtodo, clase. Debido a que la salida de JavaDoc es a formato HTML, entonces se pueden agregar a estas palabras, las etiquetas comunes de HTML.

Ejemplo con las clase Notas

Partimos de la siguiente clase no documentada:
public class Notas { /** * @param args */ public static int toInteger if (nota < 0) return else if (nota < 0.5) else if (nota < 1.5) else if (nota < 2.5) else if (nota < 3.5) else if (nota < 4.5) else if (nota < 5.5) else if (nota < 6.5) else if (nota < 7.5) else if (nota < 8.5) else if (nota < 9.5) else if (nota <= 10) else return -1; } public static String toString (double nota) { if (nota < 0) return "E-"; else if (nota < 3.5) return "MD"; else if (nota < 5.0) return "IN"; else if (nota < 6.0) return "SU"; else if (nota < 7.5) return "BI"; else if (nota < 8.5) return "NO"; else if (nota <= 10.0) return "SB"; else return "E+"; } } (double nota) { -1; return 0; return 1; return 2; return 3; return 4; return 5; return 6; return 7; return 8; return 9; return 10;

Sobre esta clase vamos a documentar primero la clase en s aadiendo autor, versin . Posteriormente comentaremos los mtodos describiendo autor, parmetros y tipo devuelto, aadiendo los siguientes comentarios a mi cdigo:
/** * <h2> Clase usada en la conversin de elementos. </h2> * @author Enrique Mora Moral * @verison 1.0 * @version 1.0 */ public class Notas { /** * Metodo <b> toInteger </b> cambia la nota de tipo double a entero. * @author Enrique Mora Moral * @param nota: nota de entrada de tipo double * @return devuelve una conversin de double a entero con redondeo */ public static int toInteger (double nota) { if (nota < 0) return -1; else if (nota < 0.5) return 0; else if (nota < 1.5) return 1; else if (nota < 2.5) return 2; else if (nota < 3.5) return 3; else if (nota < 4.5) return 4; else if (nota < 5.5) return 5; else if (nota < 6.5) return 6; else if (nota < 7.5) return 7; else if (nota < 8.5) return 8; else if (nota < 9.5) return 9; else if (nota <= 10) return 10; else return -1; } /** * Metodo <b> toSring </b> convierte nota double a cdigos en texto. * @author Enrique Mora Moral * @param nota * @return un String con el cdigo de la nota. */ public static String toString (double nota) { if (nota < 0) return "E-"; else if (nota < 3.5) return "MD"; else if (nota < 5.0) return "IN"; else if (nota < 6.0) return "SU"; else if (nota < 7.5) return "BI"; else if (nota < 8.5) return "NO"; else if (nota <= 10.0) return "SB"; else return "E+"; } }

Para el correcto uso de JavaDoc tenemos que tener en cuenta: Comentar cada clase, mtodo inmediatamente antes de su declaracin. Se pueden usar etiquetas HTML para sealar ciertos elementos. Como la descripcin de la clase en <h2< o el nombre del mtodo con Bold <b> Una vez realizado este proceso podemos ejecutar JavaDoc desde el men principal opcin Proyecto-Generar JavaDoc... Recordar que JavaDoc es una utilidad externa a Eclipse perteneciente a Java que se puede ejecutar desde la linea de comandos.

En las siguientes ventanas seleccionamos el proyecto y clases a documentar, mediante las opciones por defecto y finalizamos la generacin de documentacin. Seleccin del Proyecto.

Filtro bsico de elementos a introducir.

Opciones generales de JavaDoc.

Una vez finalizado el proceso, se ha construido la documentacin HTML asociada a nuestro proyecto. En la parte inferior del Explorador de proyectos aparece una nueva carpeta doc donde se encuentra la documentacin recin creada:

Si se entra a la carpeta doc y abrimos con el navegador el archivo index.html se muestra la siguiente ayuda sobre las clases de nuestro proyecto.