Professional Documents
Culture Documents
/** * Este metodo regresa la clave del genero * @return La clave del genero */
ITSON
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.
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
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
* @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
*/ 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
@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
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
ITSON
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
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
10
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
11
Figura 9
Figura 10
ITSON
12
Figura 11
ITSON