Eclipse - Como generar Javadoc con el eclipse?

- Integracin Eclipse con Javadoc

Hola, generalmente cuanto tenemos un proyecto y queremos adjuntar documentacion de los metodos, parametros, etc. recurrimos al Javadoc, pero no se suele enviar un html (que generalmente lo encontramos en la web con las definiciones).

Como generar Javadoc con el eclipse?

Selecionamos el proyecto que necesitamos obtener el Javadoc y vamos a Project -> Generate Javadoc...

Aparecer:

Si el campo de Javadoc command esta vaco indicamos la ruta de nuestro javadoc.exe (En mi caso puntual C:\Program Files\Java\jdk1.6.0_23\bin\javadoc.exe). Luego indicamos la carpeta de destino y seguimos el asistente. Si todo salio bien luego vamos a nuestro destino y vamos a encontrar los html. los abrimos y deberamos ver ya el javadoc!

Saludos

Uso de JavaDoc

1 Comentarios en Java 2 Formato de comentarios JavaDoc 3 La herramienta javadoc 4 Usando javadoc desde JCreator

1 Comentarios en Java
Los comentarios, anotaciones en el cdigo que el compilador ignora pero son tiles para los programadores, existen en los lenguajes de programacin desde el principio. Desde hace mucho tiempo se observ que en realidad los comentarios se usaban para dos propsitos diferentes: Para explicar el propsito de sentencias o grupos de sentencias. Estos comentarios son tiles para el propio autor del cdigo, y para otros que quieran modificar ese cdigo. Comentarios explicando qu hace una "pieza" cerrada de cdigo. Estos comentarios son tiles para quien quiere utilizar esta "pieza" en su propio programa, y que por tanto est necesita saber lo qu hace, no cmo se las ha arreglado el programador para conseguir este resultado. Al disear Java se distinguieron desde el principio ambas posibilidades. Para el primer tipo, comentarios "internos" se usan los caracteres // seguidos del comentario, o /* .... */ con el comentario en el lugar de los puntos suspensivos. La primera posibilidad indica que el resto de la lnea, tras las dos barras, es un comentario, mientras que la segunda se usa para comentarios de ms de una lnea. Por ejemplo, un fragmento de cdigo que calcula la suma 1+3+5+ ... +99 y muestra el resultado por pantalla:
int suma = 0; // al principio la suma vale 0 // vamos sumando cada uno de los cuadrados entre 1 y 100 y acumulando el resultado for (int i=1; i<=99; i+=2) suma += i; // finalmente mostramos el resultado por pantalla System.out.println(suma); // por cierto, que valor se mostrar por pantalla?

El segundo tipo, los usados para explicar qu hace un cdigo son los llamados en Java comentarios JavaDoc, y se escriben comenzando por /** y terminando con */ , pudiendo ocupar varias lneas. Mientras que los comentarios usuales no tienen ningn formato, los comentarios JavaDoc siguen una estructura prefijada que describimos en el siguiente apartado.

2 Formato de los comentarios JavaDoc

Los comentarios JavaDoc estn destinados a describir, principalmente, clases y mtodos. Como estn pensados para que otro programador los lea y utilice la clase (o mtodo) correspondiente, se decidi fijar al menos parcialmente un formato comn, 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 lnea. Por ejemplo esta es una clase para representar nmeros crculos (reducida al mnimo):
package figuras; /** * Una clase para representar crculos situados sobre el plano. * Cada crculo queda determinado por su radio junto con las * coordenadas de su centro. * @version 1.2, 24/12/04 * @author Rafa Caballero */ public class Crculo { protected double x,y; // coordenadas del centro protected double r; // radio del crculo /** * Crea un crculo a partir de su origen su radio. * @param x La coordenada x del centro del crculo. * @param y La coordenada y del centro del crculo. * @param r El radio del crculo. Debe ser mayor o igual a 0. */ public Circulo(double x, double y, double r) { this.x=x; this.y = y; this.r = r; } /** * Clculo del rea de este crculo. * @return El rea (mayor o igual que 0) del crculo. */ public double rea() { return Math.PI*r*r; } /** * Indica si un punto est dentro del crculo. * @param px componente x del punto * @param py componente y del punto * @return true si el punto est dentro del crculo o false en otro caso. */ public boolean contiene(double px, double py) { /* Calculamos la distancia de (px,py) al centro del crculo (x,y), que se obtiene como raz cuadrada de (px-x)^2+(py-y)^2 */ double d = Math.sqrt((px-x)*(px-x)+(py-y)*(py-y)); // el crculo contiene el punto si d es menor o igual al radio

return } }

d <= r;

Como se ve, y esto es usual en JavaDoc, la descripcin de la clase o del mtodo no va precedida de ningn indicador. Se usan indicadores para el nmero de versin (@version), el autor (@author) y otros. Es importante observar que los indicadores no son obligatorios; por ejemplo en un mtodo sin parmetros no se incluye obviamente el indicador @param. Tambin puede darse que un comentario incluya un indicador ms de una vez, por ejemplo varios indicadores @param porque el mtodo tiene varios parmetros. Vamos a hacer un resumen de los indicadores ms usuales: @author nombreDelAutor descripcin. Indica quin escribi el cdigo al que se refiere el comentario. Si son varias personas se escriben los nombres separados por comas o se repite el indicador, segn se prefiera. Es normal incluir este indicador en el comentario de la clase y no repetirlo para cada mtodo, a no ser que algn mtodo haya sido escrito por otra persona. @version nmeroVersin descripcin. Si se quiere indicar la versin. Normalmente se usa para clases, pero en ocasiones tambin para mtodos. @param nombreParmetro descripcin. Para describir un parmetro de un mtodo. @return descripcin. Describe el valor de salida de un mtodo. @see nombre descripcin. Cuando el trozo de cdigo comentado se encuentra relacionada con otra clase o mtodo, cuyo nombre se indica en nombre. @throws nombreClaseExcepcin descripcin. Cuando un mtodo puede lanzar una excepcin ("romperse" si se da alguna circunstancia) se indica as. @deprecated descripcin. Indica que el mtodo (es ms raro encontrarlos para una clase) ya no se usa y se ha sustituido por otro. Observacin : JavaDoc es mucho ms completo de lo que hemos descrito en este primer vistazo. Por ejemplo, adems de para clases y mtodos, tambin existen comentarios JavaDoc para paquetes. Los interesados pueden consultar la ayuda de Java.

3 La herramienta javadoc
Hemos visto cul es el formato de los comentarios JavaDoc. Aparte de obtenerse comentarios ms fciles 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 documentacin de los programas. Para ello se utiliza la herramienta javadoc parte de JDSK. El formato ms sencillo de esta herramienta, cuando se emplea desde lnea de comandos es: javadoc fichero.java Por ejemplo: javadoc Crculo.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 documentacin de la clase. Por ejemplo, esta es el fichero Crculo.html que genera javadoc (entre otros) al procesar el fichero Crculo.java (para distinguirlo de este documento muestro el fondo en color, aunque en realidad es blanco):

Package Class Tree Deprecated Index Help

PREV CLASS NEXT CLASS SUMMARY: NESTED | FIELD | CONSTR | METHOD FRAMES NO FRAMES All Classes DETAIL: FIELD | CONSTR | METHOD

figuras

Class Crculo
java.lang.Object figuras.Crculo public class Crculo extends java.lang.Object

Una clase para representar crculos situados sobre el plano. Cada crculo queda determinado por su radio junto con las coordenadas de su centro.

Constructor Summary
Crculo(double x, double y, double r)

Crea un crculo a partir de su origen su radio.

Method Summary
double rea()

Clculo del rea de este crculo.

boolean contiene(double px, double py)

Indica si un punto est dentro del crculo.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
Crculo
public Crculo(double x, double y, double r)

Crea un crculo a partir de su origen su radio. Parameters: x - La coordenada x del centro del crculo. y - La coordenada y del centro del crculo. r - El radio del crculo. Debe ser mayor o igual a 0.

Method Detail
rea
public double rea()

Clculo del rea de este crculo. Returns: El rea (mayor o igual que 0) del crculo.

contiene
public boolean contiene(double px, double py)

Indica si un punto est dentro del crculo. Parameters: px - componente x del punto py - componente y del punto Returns: true si el punto est dentro del crculo o false en otro caso. Package Class Tree Deprecated Index Help
PREV CLASS NEXT CLASS SUMMARY: NESTED | FIELD | CONSTR | METHOD FRAMES NO FRAMES All Classes DETAIL: FIELD | CONSTR | METHOD

Como se ve, es un fichero muy completo, y con un aspecto agradable, generado sin apenas esfuerzo. En caso de que nuestra aplicacin contenga varias clases la herramienta se encarga de generar ficheros ndice y de establecer los enlaces entre todas ellas. La herramienta es, por tanto fundamental en el desarrollo en Java, aunque durante el curso no la usar apenas al hacer tan slo programas "de juguete". Aviso: Un programa mal documentado es, bsicamente, un programa intil. Esto es as porque los programas no son nunca productos cerrados, acabados; siempre se encuentran errores que corregir, posible ampliaciones. Y el cdigo que nos parece evidente un da se convierte en crptico

e inmanejable una semana despus. La herramienta javadoc ayuda a mantener la documentacin del cdigo en un formato legible y prctico.

4 Usando javadoc desde JCreator

Si tenemos instalado el compilador Eclipse la herramienta javadoc est directamente accesible. Si en cambio tenemos JCreator (siempre ms espartano) no tendremos acceso directo a javadoc, pero podemos configurar el entorno para crear dicho acceso. Vamos a ver como se hace. Dentro del men Configure elegir la opcin Options . En la ventana que aparece, hacemos click sobre la palabra Tools que aparece en la lista de la izquierda. La pantalla tendr el aspecto:

Pulsar el botn New y del men desplegable que aparece elegir la primera opcin, Dos Command . En la ventana que aparece nos pregunta el nombre del comando (Dos Command:) escribiremos, por ejemplo: javadoc . Ahora a la palabra tools a la izquierda de la ventana debe tener una subopcin con el nombre javadoc . Hacer click sobre esta subopcin (aparece enmarcada en un crculo en la figura de abajo). Nos cambiar el lado derecho de la ventana para que introduzcamos los datos de llamada a la herramienta. Al lado de "Arguments:" escribir javadoc.exe -d "$[PrjDir]" $[JavaFiles] , y al lado de "Initial directory:" $[JavaHome]\bin . El aspecto final ser:

Ahora pulsamos el botn "OK" y ya tenemos el acceso a javadoc listo. Para usarlo slo hay que pulsar Ctrl+1 , o hacer click sobre la llave inglesa marcada con 1. Al hacerlo se llamar a javadoc para todos los ficheros java del proyecto. Para poder adems ver los ficheros generados podemos aadir otra herramienta ms, como se describe en el punto siguiente. Repetimos el proceso anterior para crear un nuevo acceso a herramientas (Configure+Options, pulsar sobre Tools, pulsar sobre el botn New y elegir la primera opcin "Dos Command"). Cuando salga la ventana pidiendo el dato "Dos Command" introducimos el texto explorer "$[PrjDir]\index.html" Pulsamos a continuacin OK, y ya tenemos listo en Ctrl+2 , o al hacer click sobre la llave inglesa marcada con 2, un acceso al fichero "index.html" generado por la herramienta javadoc (si no hubo errores y el fichero pudo generarse, claro). El fichero "index.html" contiene el

ndice de todos los documentos creados para las diferentes clases de la aplicacin; desde l podemos hacer click sobre el nombre de la clase que deseemos en particular. Observacin: Por supuesto los pasos anteriores slo hay que hacerlos una vez; la prxima vez que entremos en JCreator se podrn usar las herramientas directamente.