Tutoriales

Documentar código Java con JavaDoc

Por

13 julio, 2003

115402

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
 */

/**
 <font color="#0000FF">* Clase que comienza la estructura de escepciones
 * @author  Roberto Canales
 * @since  1.0
 * @see Visitar <a href="http://www.adictosaltrabajo.com">www.adictosaltrabajo.com</a></font>
 */
class RCException extends Exception
{
    void depura(String psError)
    {
        System.out.println("Error: " + psError);
    }


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

<font color="#0000FF">/**
 *
 * @author  Roberto Canales
 * @since  1.0
 * @see Visitar <a href="http://www.adictosaltrabajo.com">www.adictosaltrabajo.com</a>
 */
</font>public class ejemplojavadoc {

 <font color="#0000FF">   /** Constantes publicas de gestion errores*/
 </font>   public static final int ERROR   = 0;
    public static final int LOG     = 1;
    public static final int INFO    = 2;

 <font color="#0000FF">   /** Constructor por defecto */
 </font>   public ejemplojavadoc() {
    }

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


 <font color="#0000FF">   /**
     * @param args Array de argumentos
     */
</font>    public static void main(String[] args) {
 <font color="#0000FF">       /** Construimos un objeto no estático */
</font>        ejemplojavadoc objetoAuxiliar = new ejemplojavadoc();

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

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

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

        return true;
    }
}

* 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 <a href="http://www.adictosaltrabajo.com">www.adictosaltrabajo.com</a>

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 <a href="http://www.adictosaltrabajo.com">www.adictosaltrabajo.com</a>

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 <code>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 ..

Documentar código Java con JavaDoc

Documentación con JavaDoc

Dejar respuesta Cancelar respuesta

Envíanos tu tutorial

Documentación con JavaDoc

Artículo relacionadosMás del autor

SQL: función de ventana LAG y LEAD

Sector STEM y talento femenino: Una relación en construcción

Microfrontends con Module Federation

Cómo hacer un buen CV

¿DevOps? Eso es cosa del pasado, conoce MLOps

Dejar respuesta Cancelar respuesta

Envíanos tu tutorial

Artículo relacionados Más del autor