Capturar webcam con VB.NET

¿Que haremos? Crearemos una aplicación en Visual Studio, la cual hará uso de una webcam para capturar el video en frames independientes y depositarlos en memoria para despues mostralos al usuario a través de un picturebox y un Timer para crear la ilusión de movimiento. ¿Porque lo haremos? Porque es justo y necesario ¿Que necesitamos? [...]

Envío de correo con JavaMail/Netbeans

JavaMail es una expansión de Java que facilita el envío y recepción de e-mail desde código java. JavaMail implementa el protocolo SMTP (Simple Mail Transfer Protocol) así como los distintos tipos de conexión con servidores de correo -TLS, SSL, autentificación con usuario y password, etc [Según SantaWikipedia] ¿Qué necesitamos? JavaMail 1.4.5 Java y Netbeans 6.9 [...]

Proyecto de base de datos Firebird VB

En este proyecto realizaremos una aplicación de base de datos Firebird con el lenguaje de programación de Visual Basic de Microsoft, este proyecto tendrá las funciones básicas de gestión INSERT, DELETE, UPDATE y una interfaz de usuario para utilizarlas. ¿Que necesitamos? Visual Studio 2008 o superior Firebird última versión Firebird ADO.NET Data Provider. Conocimientos básicos [...]

Imprimir imagen con Print

La siguiente clase hace uso de PRINT para imprimir una imagen que se encuentra en un variable de tipo FileInputStream, esta clase a su vez es implementada desde una interfaz que hace fácil su uso, la clase así como todo el proyecto esta comentado. import java.io.File; import javax.print.Doc; import java.io.IOException; import javax.print.DocFlavor; import javax.print.SimpleDoc; import java.io.FileInputStream; [...]

Code Army Bolivia

7/7/12

Creación y uso de Javadoc con Netbeans

JAN29

Javadoc es un paquete de desarrollo de java que nos genera documentación sobre nuestro proyecto de cada una de nuestras clases en una jerarquía de árbol.

Su uso es recomendable para todo proyecto, incluido los proyectos pequeños porque nos ayuda a tener siempre un código bien documentado, el único contra que tiene su uso, es que es muy tedioso documentar cada paso que se da al escribir el código (en general por los programadores flojos como yo), por lo demás, es una buena regla de programación.

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 versión del proyecto
@see - Añade una referencia a una clase, método o enlace web
@param - Nombre de parámetro utilizado en un método incluido su significado
@return - El resultado de un método incluido su descripción
@exception - Nombre de la excepción mas una descripción
@throws - Nombre de la excepción mas una descripción
@deprecated - Añade una alerta al usuario de que el método que sigue a continuación ya no debe usarse y que será eliminado en versiones posteriores.


Al escribir los comentarios también podemos hacer uso de algunas etiquetas HTML para decorar un poco más nuestra documentación.


Para indicarle a Javadoc que queremos incluir documentación, 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 instrucción @see con un enlace a una página web, también podemos agregar la versión 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 {
...
}
También podemos documentar las variables que hacen parte de nuestro código
/**
 * 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 método es recomendable documentar los parámetros de entrada, si es que los tuviera, y si este método retorna algún resultado, utilizar la marca @return, si por el contrario el método es de la forma VOID, no se usa nada. Así también para las excepciones que puedan ocurrir se usa @exception. En la descripción del método, se puede incluir un ejemplo de uso encerrado en las etiquetas PRE, por ejemplo:
    /**
     * Método 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 método, podremos ver que Netbeans nos despliega toda la información en cuando se hace referencia al nombre StringToDate.
Cuando tenemos varias versiones de un proyecto y vamos actualizando los metodos, antes de eliminar los métodos que ya no se harán uso, es preferible, primero alertar al usuario que ciertas funciones dejaran de existir en versiones posteriores, para esto, en la descripción se añade la marca @deprecated, y la marca @see, que hace referencia a la función de reemplazo, es decir, supongamos que en una primera versión tenemos un método llamado Suma pero que en una nueva versión se decide crear una nueva versión suma_enteros, entonces lo que debemos hacer es añadir en la documentación de Suma, la alerta de que esta función ya no se utilizara más y que es mejor usar la nueva función suma_enteros, es decir:
/**
     * Metodo que suma dos enteros y retorna el resultado, gran cosa no :)
     * @param a Número Entero
     * @param b Número 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
     * @param a Número Entero
     * @param b Número Entero
     * @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 método Suma, este nos aparecerá con un subrayado y con la alerta correspondiente:
El código 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 + "'" );              
    }

    /**
     * Método 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 :)
     * @param a Número Entero
     * @param b Número 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
     * @param a Número Entero
     * @param b Número Entero
     * @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

1 comentarios:

daveG dijo...

Muy bueno. Siempre es gran idea documentar el código, aunque lo pasamos por alto.

Post recomendado