Documentacion de código con Javadoc
Javadoc y la Documentación de código
JavadocTM es una herramienta desarrollada por la compañia Sun microsystems(quienes crearon JAVA) que permite generar documentacion en formato HTML a partir de los comentarios que se colocan en los archivos de código fuente. Javadoc se incluye dentro del kit de desarrollo que proporciona Sun microsystems sin ningun costo para el desarrollo en la plataforma JAVA (JDK).
Importancia de la documentación
Yo sé que estarán de acuerdo conmigo cuando digo que el documentar el código fuente es algo muy útil(quizas deberia decir ético…xD) que permite que nuestros programas sean legíbles y faciles de mantener ya sea por otros programadores o por nosotros mismos. Una buena documentación conlleva a un software legible y sobre todo mantenible.
Ahora bien, digamos que existen dos formas de realizar esta documentación; realizar manualmente la documentación en el formato deseado, la otra opción es utilizar una herramienta que permita generar la documentación de forma automática apoyandose de lo que comentamos al momento de escribir el código fuente, tarea común de todo progrador. Este documento esta intentado para tratar la segunda opción la cual se hace realidad utilizando la herramienta JAVADOCTM, especificamente para el lenguaje JAVA.
Manos a la obra
En este post muestro de manera sencilla la forma en que se deben colocar los comentarios, algunos etiquetas especiales y tambien como realizar la compilación para generar los archivos HTML que contienen la documentación del software que hemos desarrollado.
Tipos de comentarios
En java existen 3 tipos de comentarios; de una sola línea (//), comentarios de varias líneas(/*…*/), estos 2 tipos muy comunes en muchos lenguajes con sintaxis parecidas a los lenguajes C/C++, ademas de estos 2 Java introduce un tercer tipo, el de la documentación(/**…*/).
A continuación se puede apreciar cada uno de estos tipos de comentario:
public class MiClase {
/**
Este es un tipo de comentario especial
porque todo lo que escriba aqui sera parte
de la docuemtacion que geraremos con JAVADOC.
*/
public static void main(String[] argumentos)
{
//Este es un comentario normal de una sola linea
System.out.println("Comentario 1...");
/*
Ahora estamos con un comentario
de varias lineas.
Esta linea tambien...
*/
System.out.println("Comentario 2...de varias lineas");
}
}
En el ejemplo el primer tipo de comentario es el que nos importa, estos comentarios delimitados por los símbolos /** y */(notese que son 2 asteriscos en la apertura) son los que utiliza JAVADOC para incluir dentro de la documentacion.
Especificaciones de uso
Hay algunos puntos que se deben de tomar en cuenta a la hora de documentar código mediante los comentarios que a continuacion se mencionan:
- Los comentarios deben ser posicionados inmediatamente antes de la seccion de código a documentar, clase, interfaz, método, etc. De lo contrario no funcionará.
- Los comentarios estan compuestos por 2 partes; una descripción del código y una sección de etiquetas( mas adelante las tratamos).
- Es posible utilizar las etiquetas HTML para especificar el formato de la documentación resultante.
- La primera oracion de cada comentario debe ser una descripción concisa y completa del código a documentar. La descripción termina ya sea con una línea en blanco o un salto de línea.
- …
Estos son solo unos cuantos puntos a tomar en cuenta cuando documentemos con JAVADOC. Ahora pasemos a otro punto.
Las etiquetas
Las etiquetas o tags son palabras reservadas que JAVADOC reconoce en el momento de analizar el código da la interpretación adecuada, hay 2 tipos:
-
Etiquetas de bloque: Ubicadas al inicio de línea y precedidas por el simbolo arroba
@, por ejemplo,@author. -
Etiquetas en línea (inline): Estas etiquetas se encierran dentro de llaves y tienen la particularidad de poder ser utilizadas en cualquier parte dentro del comentario, no necesariamente al inicio de línea. Las etiquetas son de la siguiente forma,
{@docRoot}.
A continuación algunas etiquetas muy comunes que podemos encontrar dentro de la documentacion, solo unas cuantas:
-
@authornombreDeAutor: Obviamente sirve para especificar el nombre del autor del software. -
@deprecatedtextoObsoleto: Permite describir partes del código que ya no son o no serán soportadas, que ya estan obsoletas. -
@codetexto: Esta etiqueta es equivalente a la etiqueta <code> y </code> que permiten que texto no sea interpretado como como palabra clave, si asi lo fuere y de esta forma poder emplear cualquier cosa que necesitemos. -
@exception y @throwsdescripcionDeExcepcion: Nos perimite describir las posibles excepcioenes que pudieran ser arrojadas (throw) por ciertas operaciones. -
@paramdescripcion: Esta etiqueta permite describir los parametros pasados a los métodos. -
@returndescripcionDeRetorno: Describe el tipo de dato que devuelve un determinado método. -
@seereferencia: Tiene la finalidad de colocar referencias, desde simple texto, hasta enlaces a la web o bien a otras partes de la documentación.
Pues bien, estas son solo algunas de las etiquetas soportadas por JAVADOC, al final de este documento dejo la referencia a la documentacion oficial de esta herramienta donde se detallan más etiquetas y otros temas.
Un ejemplo
/**
@author Rendon Pablo Rafael
*/
public class PilaDinamica{
private lNodo oApuntador; //El fomoso tope
/**
Contructor de clase que inicializa la pila.
*/
public PilaDinamica(){ oApuntador = null; }
/**
Verifica se la pila se encuentra Vacia o no.
@return Retorna un valor de tipo boolean indicando el estado de la pila.
*/
public boolean estaVacia(){ return (oApuntador == null); }
/**
Inserta un nuevo valor el tope de la pila.
@param iVal Un valor de tipo entero, el cual se va a colocar en el punto mas alto de la pila.
*/
public void push(int iVal)
{
lNodo nuevo = new lNodo(iVal);
nuevo.pSig = null;
if(estaVacia()){
oApuntador = nuevo;
}else{
nuevo.pSig = oApuntador;
oApuntador = nuevo;
}
}
/**
Este metodo se encarga de derrivar el elemento que se encuentra en el punto mas alto de la pila y lo retorna.
@return El elemento que se encuentra en la posicion mas alta de la pila, entero.
*/
public int pop()
{
int iTemp = oApuntador.valor();
oApuntador = oApuntador.pSig;
return iTemp;
}
}
Este es un ejemplo muy sencillo donde se muestran solo algunos elementos que podemos utilizar en la documentación.
NOTA: En el código de ejemplo no esta completo, falta la implementacion de la clase lNodo…No es intención que este código sea de utilidad.
Generar documentación
La manera mas sencilla de generar documentación a partir del código fuente es con el siguiente comando:
1 | javadoc CódigoFuente.java |
Donde CódigoFuente.java es el nombre de nuestro archivo de código. Sin mas que pensar ejecutamos la operacion necesaria y a continuación se generan los archivos de documentación.
Como podran observar utilizar Javadoc no es tan complicado y mucho menos dificil de entender, por este post es todo, espero que les guste el tema y sobre todo que este material pueda ser de utilidades para ustedes. Cualquier duda, comentario o corrección será bienvenida. COMENTEN!!!
excelente ayuda, te agradeceria que subieras algo de programacion en c++, especificamente acerca de como funciona el operador “::”, ya que he investigado pero no he encontrado mucho,,,graciaas de antemano