Javadoc con NetBeans

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:

/** * Este metodo regresa la clave del genero * @return La clave del genero */

ITSON

Manuel Domitsu Kono

Javadoc con NetBeans

public String getCveGenero() { return cveGenero; }

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

Figura 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: Medio.java
/* * Medio.java * * Creada el 8 de septiembre de 2006, 01:14 PM */ package objetosNegocio;

ITSON

Manuel Domitsu Kono

Javadoc NetBeans 5.0

import objetosServicio.Fecha; /** * Esta clase contiene los atributos y mtodos comunes a las clases * Cancion y Pelicula del programa AmanteMusica * * @author mdomitsu */ public class Medio { protected String clave; protected String titulo; protected Genero 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, Genero 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; } /** * 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

ITSON

Manuel Domitsu Kono

Javadoc con NetBeans

* @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 Genero getGenero() { return genero; } /** * Establece el gnero de la cancin o pelcula * @param genero Gnero de la cancin o pelcula */ public void setGenero(Genero 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 * @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

ITSON

Manuel Domitsu Kono

Javadoc NetBeans 5.0

*/ 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.getNombre() + ", " + duracion + ", " + fecha; } }

Etiquetas Javadoc
En la tabla 2.1 se muestran las etiquetas de documentacin. Tabla 2.1
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.

Edicin 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:

ITSON

Manuel Domitsu Kono

Javadoc con NetBeans

1. Coloque el cursor en la lnea anterior a la lnea con el nombre del atributo o mtodo al que desea agregarle un comentario de documentacin y teclee los caracteres /**, figura 2.

Figura 2 2. Al presionar la tecla Intro, veremos que NetBeans ha agregado un esqueleto para la documentacin del elemento, figura 3. Note que en este caso le ha agregado una etiqueta Javadoc por cada parmetro del constructor. NetBeans har algo similar si el mtodo regresa un valor o si lanza una excepcin. 3. En la segunda lnea del comentario (la resaltada en azul) agregue la descripcin de lo que hace el mtodo. 4. Al lado derecho del nombre del parmetro de cada etiqueta @param describa el propsito del parmetro. 5. Al lado derecho de cada etiqueta @return describa qu regresa el mtodo. 6. Al lado derecho del nombre de la excepcin de cada etiqueta @throws describa por qu razn se lanza la excepcin.

ITSON

Manuel Domitsu Kono

Javadoc NetBeans 5.0

Figura 3 7. Si hay atributos no privados agregue un comentario de documentacin, describiendo su uso.

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 incluido en el cdigo. Para generar la documentacin Javadoc seleccione de la barra de men de NetBeans la opcin Run/ Generate Javadoc (nomProyecto) donde nomProyecto es elnombre de proyecto, por ejemplo amanteMusicaObjNeg, figura 4

ITSON

Manuel Domitsu Kono

Javadoc con NetBeans

Figura 4 Otra forma de generar la documentacin Javadoc, es hacer clic con el botn derecho en el nombre del proyecto en el rbol de proyectos y seleccione la opcin Generate del men emergente, figura 5.

Figura 5 En ambos casos, NetBeans genera las pginas HTM Javadoc, mostrando el avance en la ventana de salida, figura 6.

ITSON

Manuel Domitsu Kono

Javadoc NetBeans 5.0

Figura 6 Al terminar, Netbeans abre el navegador Web predeterminado y despliega en l la pgina inicial de la documentacin del proyecto como se muestra en la figura 7.

Figura 7 Haciendo clic en las ligas podemos ver la documentacin de las diferentes clases del proyecto. Por ejemplo, en la figura 8 se muestra la documentacin de la clase Genero.

ITSON

Manuel Domitsu Kono

10

Javadoc con NetBeans

Figura 8

Configuracin de Javadoc
Podemos configurar como NetBeans generar la documentacin Javadoc para el proyecto 1. Haga clic con el botn derecho en el nombre del proyecto, en el rbol de proyectos y seleccione la opcin Properties en el men emergente, figura 9. 2. Aparecer un cuadro de dilogo para establecer las propiedadades del proyecto. Seleccione el nodo Documenting en el rbol Categories, figura 10, y seleccione las opciones deseadas. y haga clic en el botn OK.

ITSON

Manuel Domitsu Kono

Javadoc NetBeans 5.0

11

Figura 9

Figura 10

ITSON

Manuel Domitsu Kono

12

Javadoc con NetBeans

Ubicacin de los Archivos con la Documentacin

La figura 11, 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.

Figura 11

ITSON

Manuel Domitsu Kono