icono_twiter icono LinkedIn icono Facebook Icono Xing
Roberto Canales Mora

Creador y propietario de AdictosAlTrabajo.com, Director General de Autentia S.L., Ingeniero Técnico de Telecomunicaciones y Executive MBA por el Instituto de Empresa 2007.
Twitter:

Autor de los Libros: Planifica tu éxito: de aprendiz a empresario y Informática profesional, las reglas no escritas para triunfar en la empresa

Puedes consultar mi CV y alguna de mis primeras aplicaciones (de los 90) aquí

Ver todos los tutoriales del autor

Fecha de publicación del tutorial: 2003-07-13

Tutorial visitado 64.818 veces Descargar en PDF

Documentación con JavaDoc

Cuando desarrollamos aplicaciones, de un modo paralelo debemos construir la documentación.

Desde las primeras versiones de Java e incluso para documentar las propias libreriís del lenguaje, se utiliza un mecanismo llamado JavaDoc para garantizar que el código y su documentación estan sincronizados.

Este sistema consiste en incluir comentarios en el código, utilizando unas etiquetas especiales, que despues pueden procesarse y generar un juego navegable de documento HTML.

Estos comentarios estan incluidos en bloques entre las etiquetas /** y */

Al igual que obtenemos en binario de un programa java con javac, podemos obtener la documentación ejecutando sobre los mismos elementos el comando javadoc.

Los entornos de desarrollo avanzado ya hacen muchas de estas cosas por nosostros ..... solo tenemos que saber encontrarlas.

Vamos a crear una clase y ver lo que se va generando.

Buscamos en el menú.... y vemos que en herramientas .... podemos generar el documento JavaDoc..

 

Las etiquetas disponibles son:

Etiqueta Introducida en JDK/SDK
@author 1.0
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0

Aunque pongamos todas las etiquetas, no todas se muestran. En función de los parametros que se pasen al comando javadoc, selecionamos cuales queremos ver.

Aquí podemos ver como configurarlo en FORTE o NETBEANS. Activamos la opción de ver el autor.

Y comprobamos que disponemos de una nueva etiqueta en nuestra documentación.

En la documentación estandar de Java podemos comprobar donde podemos utilizar cada una de las distintas etiquetas:

http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#{@link}

Os mostramos un pequeño ejemplo ...

 /*
 * ejemplojavadoc.java
 *
 * Created on July 5, 2003, 4:24 AM
 */

/**
 * Clase que comienza la estructura de escepciones
 * @author  Roberto Canales
 * @since  1.0
 * @see Visitar www.adictosaltrabajo.com
 */
class RCException extends Exception
{
    void depura(String psError)
    {
        System.out.println("Error: " + psError);
    }


    RCException(String psError)
    {
        super(psError);
        depura(psError);
    }
}

/**
 *
 * @author  Roberto Canales
 * @since  1.0
 * @see Visitar www.adictosaltrabajo.com
 */
public class ejemplojavadoc {

    /** Constantes publicas de gestion errores*/
    public static final int ERROR   = 0;
    public static final int LOG     = 1;
    public static final int INFO    = 2;

    /** Constructor por defecto */
    public ejemplojavadoc() {
    }

    void depura(String sError)
    {
        System.out.println("ejemplojavadoc: " + sError);
    }


    /**
     * @param args Array de argumentos
     */
    public static void main(String[] args) {
        /** Construimos un objeto no estático */
        ejemplojavadoc objetoAuxiliar = new ejemplojavadoc();

        try
        {
                objetoAuxiliar.ejecuta();
        }
        catch(RCException e)
        {
            objetoAuxiliar.depura("Excepcion = " + e.getMessage());
        }
    }

    /**
     *  Punto de entrada a la aplicación
     *  @exception RCException Se genera una excepción genérica.
     *  @return true
     */
    public boolean ejecuta() throws RCException
    {
        /** Retornamos true por defecto */
        int error = 0;

        if(error == 0)
        {
            throw new RCException("Invocamos excepciones");
        }

        return true;
    }
}
    

Las marcas utilizada por defecto, se pueden extender y crear otras nuevas.... para ello hay que crear nuevas clases con el API de Taglet y doclets

Pero esto es otra historia ......

Sobre el Autor ..

A continuación puedes evaluarlo:

Regístrate para evaluarlo

Por favor, vota +1 o compártelo si te pareció interesante

Share |
Anímate y coméntanos lo que pienses sobre este TUTORIAL:

Fecha publicación: 2006-11-30-10:01:48

Autor:

[samyr] es buen tutorial puesto que contiene todo lo relacionado con la estructuracion de un programa en java