Tutorial 4

Javadoc con NetBeans 5.0

Javadoc y NetBeans 5.0
Javadoc es una herramienta creada por Sun Microsystems para generar documentacin en formato HTML a partir de los comentarios de documentacin incluidos en el cdigo fuente. Los comentarios de documentacin deben seguir el estndar Javadoc. NetBeans incluye tambin esa herramienta y un nmero de caractersticas para facilitar la generacin de la documentacin.

Comentarios de Documentacin en los Archivos Fuente

Podemos agregar comentarios de documentacin para las clases, interfaces, constructores, mtodos y atributos. La herramienta Javadoc extrae esos comentarios de los archivos fuente y los pone en formato HTML en archivos de documentacin. Un comentario de documentacin empieza con los caracteres /** y termina con los caracteres */. Cada comentario consiste de una descripcin seguida de una o ms etiquetas. Se pueden usar etiquetas de formateo HTML en los comentarios de documentacin. Sugerencias: Los caracteres del inicio de comentario de documentacin /** deben tener la misma sangra que el cdigo documentado. Empiece las siguientes lneas de comentario con un * con la misma sangra. Empiece la descripcin en la siguiente lnea a la que tiene los caracteres /**. Inserte un espacio en blanco entre el * y el texto descriptivo o la etiqueta.

Por ejemplo, el siguiente es un comentario de documentacin de un mtodo:

ITSON

Manuel Domitsu Kono

22

Javadoc con NetBeans 5.0

/** * Establece el intrprete de la cancin * @param interprete Intrprete de la cancin */ public void setInterprete(String interprete) { this.interprete = interprete; }

En el archivo HTML generado el comentario se muestra en la figura 1:

Figura 4.1 Note como Javadoc convirti la etiqueta @param en un encabezado. Tambin le agreg un guin que separa el nombre del parmetro de su descripcin. Cuando se escriba la parte descriptiva de un comentario, haga la primera lnea un resumen. Javadoc copia la primera oracin del comentario a la tabla de resumen de la clase, interfaz o miembro.

Ubicacin de los Comentarios de Documentacin

Se pueden insertar comentarios de documentacin para clases, interfaces, mtodos, atributos y constructores. Los comentarios de la clase o interfaz se colocan en la parte superior del archivo, despus de las sentencias import e inmediatamente antes de la declaracin de la clase o interfaz. Los comentarios de los atributos se colocan inmediatamente antes de su declaracin. Los comentarios de los mtodos y constructores se colocan inmediatamente antes de la declaracin de su firma.

Por ejemplo, el siguiente listado muestra una clase con comentarios de documentacin:

ITSON

Manuel Domitsu Kono

Tutorial 4

Javadoc NetBeans 5.0

23

Medio.java
/* * Medio.java * * Created on 8 de septiembre de 2006, 01:14 PM * * @author mdomitsu */ package objetosNegocio; import objetosServicio.Fecha; /** * Esta clase contiene los atributos y mtodos comunes a las clases * Cancion y Pelicula del programa AmanteMusica */ public class Medio { protected String clave; protected String titulo; protected String genero; protected int duracion; protected Fecha fecha; /** * Constructor predeterminado */ public Medio() { } /** * Constructor que inicializa los atributos de la clase * @param clave Clave de la cancin o pelcula * @param titulo Ttulo de la cancin o pelcula * @param genero Gnero de la cancin o pelcula * @param duracion Duracin de la cancin o pelcula * @param fecha Fecha de liberacin de la cancin o pelcula */ public Medio(String clave, String titulo, String genero, int duracion, Fecha fecha) { this.clave = clave; this.titulo = titulo; this.genero = genero; this.duracion = duracion; this.fecha = fecha; } /** * Regresa la clave de la cancin o pelcula * @return Clave de la cancin o pelcula */ public String getClave() { return clave; } /**

ITSON

Manuel Domitsu Kono

24

Javadoc con NetBeans 5.0

* Establece la clave de la cancin o pelcula * @param clave Clave de la cancin o pelcula */ public void setClave(String clave) { this.clave = clave; } /** * Regresa el ttulo de la cancin o pelcula * @return Titulo de la cancin o pelcula */ public String getTitulo() { return titulo; } /** * Establece el ttulo de la cancin o pelcula * @param titulo Titulo de la cancin o pelcula */ public void setTitulo(String titulo) { this.titulo = titulo; } /** * Regresa el gnero de la cancin o pelcula * @return Gnero de la cancin o pelcula */ public String getGenero() { return genero; } /** * Establece el gnero de la cancin o pelcula * @param genero Gnero de la cancin o pelcula */ public void setGenero(String genero) { this.genero = genero; } /** * Regresa la duracin de la cancin o pelcula * @return Duracin de la cancin o pelcula */ public int getDuracion() { return duracion; } /** * Establece la duracin de la cancin o pelcula * @param duracion Duracin de la cancin o pelcula */ public void setDuracion(int duracion) { this.duracion = duracion; } /** * Regresa la fecha de liberacin de la cancin o pelcula

ITSON

Manuel Domitsu Kono

Tutorial 4

Javadoc NetBeans 5.0

25

* @return Fecha de liberacin de la cancin o pelcula */ public Fecha getFecha() { return fecha; } /** * Establece la fecha de liberacin de la cancin o pelcula * @param fecha Fecha de liberacin de la cancin o pelcula */ public void setFecha(Fecha fecha) { this.fecha = fecha; } /** * Regresa una cadena con los valores de los atributos de una instancia de la * clase * @return Cadena con los valores de los atributos */ public String toString() { return clave + ", " + titulo + ", " + genero + ", " + duracion + ", " + fecha; } }

Etiquetas Javadoc
Se pueden usar las siguientes etiquetas en los comentarios de documentacin.
Etiqueta @author nombre Descripcin Agrega una entrada de autor con el nombre especificado en el documento. Normalmente no se incluye en la documentacin. Agrega un subencabezado con el nmero de versin especificado. Normalmente no se incluye en la documentacin. Agrega un parmetro al subencabezado Parmetros. Agrega un subencabezado Return con el texto de la descripcin. Agrega un comentario indicando que la API ha sido descontinuada. Normalmente no se incluye en la documentacin. Tipo de Etiqueta Resumen, paquete, clase, interfaz Resumen, paquete, clase, interfaz Constructor, mtodo Constructor, mtodo Paquete, clase, interfaz, atributo, constructor, mtodo Constructor, mtodo Constructor, mtodo Atributos

@versin versin_no

@param nomPar descripcin @return descripcin @deprecated texto

@exception nomClase descripcin Agrega un subencabezado Throws al documento con el nombre de la clase de la excepcin que puede lanzar. Sinnimo de @exception @throws nomClase descripcin {@value} Se utiliza con atributos estticos. Despliega el valor de la constante en la pgina de atributos constantes.

ITSON

Manuel Domitsu Kono

26

Javadoc con NetBeans 5.0

Generacin de los Comentarios de Documentacin

NetBeans nos ayuda a editar los comentarios de documentacin de los diferentes elementos de una clase: clase, atributos, mtodos. Para agregarle los comentarios de documentacin a una clase se sigue el siguiente procedimiento: 1. Haga clic con el botn derecho sobre el nombre del archivo en el rbol del proyecto y seleccione las opciones Tools/Auto Comment , de los mens emergentes, como se muestra en la figura 2.1.

Figura 2.1 2. Aparecer en la ventana de edicin la Herramienta de Auto Documentacin, que nos permite seleccionar a que elementos de la clase le vamos a agregar comentarios de documentacin, figura 2.2. 3. Seleccione uno de los elementos para agregarle los comentarios de documentacin, por ejemplo el constructor de la clase Medio(), como se muestra en la figura 2.3, y presione el botn Auto Correct.

ITSON

Manuel Domitsu Kono

Tutorial 4

Javadoc NetBeans 5.0

27

4. En el rea de texto: Tags, aparecern las etiquetas de documentacin que se le agregarn al comentario del constructor, figura 2.4. Agregue en el rea de texto: JavaDoc Comment Text, la descripcin de lo que hace el mtodo. Por ejemplo: Constructor que inicializa los atributos de la clase. 5. Seleccione, en la ventana de edicin, la pestaa de la clase Medio.java y ver que NetBeans le habr agregado al constructor un esqueleto del comentario de documentacin, como se muestra en la figura 2.5.

Figura 2.2

Figura 2.3

ITSON

Manuel Domitsu Kono

28

Javadoc con NetBeans 5.0

Figura 2.4

Figura 2.5

ITSON

Manuel Domitsu Kono

Tutorial 4

Javadoc NetBeans 5.0

29

Generacin de la Documentacin Javadoc

NetBeans puede producir un conjunto de pginas HTML Javadoc que describe las clases, constructores, mtodos y atributos, a partir de la estructura del cdigo y los comentarios de documentacin includo en el cdigo. Para generar la documentacin Javadoc podemos: 1. Hacer clic con el botn derecho en el nombre del proyecto en el rbol de proyectos, figura 2.6. 2. Seleccionar las opciones Build/Generate Javadoc for Project figura 2.6.

Figura 2.6 o podemos hacer seleccionar las opciones Build/Generate Javadoc for nombreProyecto en la barra de men de NetBeans, figura 2.7.

ITSON

Manuel Domitsu Kono

30

Javadoc con NetBeans 5.0

Figura 2.7 NetBeans genera las pginas HTM Javadoc, mostrando el avance en la ventana de salida, figura 2.7.

Figura 2.8 Al terminar NetBeans abre la pgina con el ndice de las pginas HTML Javadoc en el navegador Web predeterminado, figura 2.9.

Configuracin de Javadoc
Podemos configurar como NetBeans generar la documentacin Javadoc para el proyecto 1. Hacer clic con el botn derecho en el nombre del proyecto en el rbol de proyectos, figura 2.10. 2. Seleccionar las opciones Build/Properties, figura 2.10. 3. Aparecer el cuadro de dilogo de las propiedades del proyecto, haga clic en el nodo Documenting del rbol: Categories, figura 2.11, y seleccione las opciones deseadas. y haga clic en el botn OK.

ITSON

Manuel Domitsu Kono

Tutorial 4

Javadoc NetBeans 5.0

31

Figura 2.8

Figura 2.10

ITSON

Manuel Domitsu Kono

32

Javadoc con NetBeans 5.0

Figura 2.11

Ubicacin de los Archivos con la Documentacin

La figura 2.12, muestra los archivos HTML Javadoc generados. Se encuentran dentro de la carpeta dist/javadoc que a su vez est dentro de la carpeta del proyecto.

ITSON

Manuel Domitsu Kono

Tutorial 4

Javadoc NetBeans 5.0

33

Figura 13

ITSON

Manuel Domitsu Kono