Creación y Uso de Javadoc Con Netbeans

Creacin y uso de Javadoc con Netbeans
JAN
29
Post Info
Mouse
en 9:36
1 comentarios
Permalink
Javadoc es un paquete de desarrollo de java que nos genera documentacin sobre nuestro proyecto de cada
una de nuestras clases en una jerarqua de rbol.
Su uso es recomendable para todo proyecto, incluido los proyectos pequeos porque nos ayuda a tener
siempre un cdigo bien documentado, el nico contra que tiene su uso, es que es muy tedioso documentar
cada paso que se da al escribir el cdigo (en general por los programadores flojos como yo), por lo dems, es
una buena regla de programacin.
Javadoc funciona por medio de MARCAS que le ayudan al API reconocer las partes que queremos
documentar y crear los archivos HTML.
@author - El nombre del autor del proyecto por ejemplo pepito :)

@version - La versin del proyecto
@see - Aade una referencia a una clase, mtodo o enlace web
@param - Nombre de parmetro utilizado en un mtodo incluido su significado
@return - El resultado de un mtodo incluido su descripcin
@exception - Nombre de la excepcin mas una descripcin
@throws - Nombre de la excepcin mas una descripcin
@deprecated - Aade una alerta al usuario de que el mtodo que sigue a continuacin ya no debe usarse y
que ser eliminado en versiones posteriores.
Al escribir los comentarios tambin podemos hacer uso de algunas etiquetas HTML para decorar un poco ms
nuestra documentacin.
Para indicarle a Javadoc que queremos incluir documentacin, debemos comenzar los comentarios de la
siguiente manera:
/**
* Esto para Javadoc
*/
Veamos su uso con un ejemplo.
Creamos una clase llamada "Clase_java" y en el encabezado colocamos el autor de la clase, la instruccin
@see con un enlace a una pgina web, tambin podemos agregar la versin de la clase:
/**
* @author Mouse
* @see <a href="http://www.jc-mouse.net">http://www.jc-mouse.net</a>
* @version 1.2 07 de Mayo de 2013
*/
public class Clase_Java {
...
}
Tambin podemos documentar las variables que hacen parte de nuestro cdigo
/**
* Variable privada: Nombre del autor
*/
private final String Autor = "jc Mouse";
/**
* Variable publica: Una frase para reflexionar
*/
public String Frase_del_dia = "Carpe diem";
Cuando se haga uso de estas variables comentadas, en el editor de Netbeans podremos ver algo como esto:
No debemos olvidar tambien comentar e constructor de clase
/**
* Constructor de clase
*/
public Clase_Java(){
...
}
Cuando creamos un mtodo es recomendable documentar los parmetros de entrada, si es que los tuviera, y
si este mtodo retorna algn resultado, utilizar la marca@return, si por el contrario el mtodo es de la
forma VOID, no se usa nada. As tambin para las excepciones que puedan ocurrir se usa @exception. En la
descripcin del mtodo, se puede incluir un ejemplo de uso encerrado en las etiquetas PRE, por ejemplo:
/**
* Mtodo que convierte una cadena de la forma "yyyy-MM-dd HH:mm" a Date
* <PRE> Clase_Java cj = new Clase_Java();
* Date date = cj.StringToDate("2012-10-01 12:00")</PRE>
* @param value String que debe tener la forma "yyyy-MM-dd HH:mm"
* @return Date Un objeto Date con la fecha parseada
* @exception ParseException Error de parseo, ocurre cuando no se puede convertir
un String a Date
* @since incluido desde la version 1.0
*/
public Date StringToDate( String value )
{
Date date = new Date();
SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm");
try {
date = (java.util.Date) formatter.parse( value );
} catch (ParseException ex) {
System.err.println( ex.getMessage() );
}
return date;
}
Cuando utilicemos este mtodo, podremos ver que Netbeans nos despliega toda la informacin en cuando se
hace referencia al nombre StringToDate.
Cuando tenemos varias versiones de un proyecto y vamos actualizando los metodos, antes de eliminar los
mtodos que ya no se harn uso, es preferible, primero alertar al usuario que ciertas funciones dejaran de
existir en versiones posteriores, para esto, en la descripcin se aade la marca @deprecated, y la
marca @see, que hace referencia a la funcin de reemplazo, es decir, supongamos que en una primera
versin tenemos un mtodo llamado Suma pero que en una nueva versin se decide crear una nueva
versin suma_enteros, entonces lo que debemos hacer es aadir en la documentacin de Suma, la alerta de
que esta funcin ya no se utilizara ms y que es mejor usar la nueva funcin suma_enteros, es decir:
/**
* Metodo que suma dos enteros y retorna el resultado, gran cosa no :)
* @param a Nmero Entero
* @param b Nmero Entero
* @return int Un entero que es el resultado de a + b
* @deprecated No se aconseja su uso
* @see suma_enteros( int, int )
*/
public int Suma( int a , int b)
{
return a + b;
}
/**
* Metodo que suma dos enteros positivos y retorna el resultado
* @return int Un entero que es el resultado de a + b, si los numeros son negativos,
retorna cero.
*/
public int suma_enteros( int a, int b)
{
int resultado = 0;
if( a>0 && b>0)
resultado = a + b;
return resultado;
}
Ahora, cuando se haga uso del mtodo Suma, este nos aparecer con un subrayado y con la alerta
correspondiente:
El cdigo completo de la clase es:
package jcdoc;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
/**
* @author Mouse
* @see <a href="http://www.jc-mouse.net">http://www.jc-mouse.net</a>
* @version 1.2 07 de Mayo de 2013
*/
public class Clase_Java {
/**
* Variable privada: Nombre del autor
*/
private final String Autor = "jc Mouse";
/**
* Variable publica: Una frase para reflexionar
*/
public String Frase_del_dia = "Carpe diem";
/**
* Constructor de clase
*/
public Clase_Java(){
System.out.println( this.Autor + " te aconseja '" + this.Frase_del_dia + "'" );
}
/**
* Mtodo que convierte una cadena de la forma "yyyy-MM-dd HH:mm" a Date
* <PRE> Clase_Java cj = new Clase_Java();
* Date date = cj.StringToDate("2012-10-01 12:00")</PRE>
* @param value String que debe tener la forma "yyyy-MM-dd HH:mm"
* @return Date Un objeto Date con la fecha parseada
* @exception ParseException Error de parseo, ocurre cuando no se puede convertir
un String a Date
* @since incluido desde la version 1.0
*/
public Date StringToDate( String value )
{
Date date = new Date();
SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm");
try {
date = (java.util.Date) formatter.parse( value );
} catch (ParseException ex) {
System.err.println( ex.getMessage() );
}
return date;
}
/**
* Metodo que suma dos enteros y retorna el resultado, gran cosa no :)
* @return int Un entero que es el resultado de a + b
* @deprecated No se aconseja su uso
* @see suma_enteros( int, int )
*/
public int Suma( int a , int b)
{
return a + b;
}
/**
* Metodo que suma dos enteros positivos y retorna el resultado

* @return int Un entero que es el resultado de a + b, si los numeros son negativos,
retorna cero.
*/
public int suma_enteros( int a, int b)
{
int resultado = 0;
if( a>0 && b>0)
resultado = a + b;
return resultado;
}
}
Para generar los HTML, vamos a Ejecutar -> Generar JavaDoc. y esperamos unos segundos a que nos
genere todos los archivos.
Eso es todo :), bajate el proyecto utilizado en este tutorial AQUI

Creación y Uso de Javadoc Con Netbeans

Cargado por

Copyright:

Formatos disponibles

Creación y Uso de Javadoc Con Netbeans

Cargado por

Información del documento

Descripción original:

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Creación y Uso de Javadoc Con Netbeans

Cargado por

Copyright:

Formatos disponibles

Creacin y uso de Javadoc con Netbeans

@author - El nombre del autor del proyecto por ejemplo pepito :)

Veamos su uso con un ejemplo.

No debemos olvidar tambien comentar e constructor de clase

El cdigo completo de la clase es:

* Metodo que suma dos enteros positivos y retorna el resultado

Eso es todo :), bajate el proyecto utilizado en este tutorial AQUI

También podría gustarte