Documentando con javadoc

javadoc es una herramienta de Sun para documentar el código mediante comentarios, pero a la vez provee una herramienta que permite extraer esa documentación de forma que sea útil para el usuario de la misma.

Básicamente javadoc es un programa, que toma lo comentarios que se colocan en el código con marcas especiales y construye un archivo HTML con clases, métodos y la documentación que corresponde. Este HTML tiene el formato de toda la documentación estándar de Java provista por Sun.

La documentación a ser utilizada por javadoc se escribe en comentarios que comienzan con /** (notar el doble *) y que terminan con */. A la vez, dentro de estos comentarios se puede escribir código HTML y operadores para que interprete javadoc (generalmente precedidos por @)

Vamos a ver un ejemplo concreto, dispongo de un paquete estructura_de_datos con dos clases: nodo y pila. A ambas clases les agregué comentarios javadoc:


[JAVA]
//archivo Nodo.java
package estructuras_de_datos;

/**
*
* @author Luciano
* @version 1.0
*
* @param Objeto genéricos
*/

public class Nodo {
T inf;
Nodo enlace;

/**
* Constructor de la clase
*
* @param inf elemento que se agrega a la pila
* @param enlace nodo al que se enlaza el objeto (ultimo elemento de la pila)
*/
public Nodo(T inf , Nodo enlace) {
this.inf = inf;
this.enlace = enlace;
}
}
[/JAVA]


[JAVA]
//archivo pila.java
package estructuras_de_datos;

/**
*
* @author Luciano
* @version 1.0
*
* @param Objeto generico
*/

public class Pila {

private Nodo cima;

/**
* Constructor de la clase pila
*
*/
public Pila( ) {
cima = null;
}

/**
* Indica si la pila está vacia
*
* @return true indica pila vacía
*/
public boolean vacia() {
return (cima == null);
}

/**
* Inserta un nuevo elemento a la pial
*
* @param obj objeto genérico
*/
public void insertar(T obj) {
Nodo nuevo = new Nodo (obj,cima);
cima = nuevo;
}

/**
* Elimina un elemento de la pila
*
* @return objeto genérico extraido de la pila
*/
public T eliminar() {
try {
if(vacia()) {
throw new PilaVacia();
} else {
T aux = cima.inf;
cima = cima.enlace;
return aux;
}
} catch(PilaVacia error) {
System.out.println(error.toString());
return null;
}
}
}

class PilaVacia extends Exception {
public PilaVacia() {
super();

}

@Override
public String toString() {
return "La pila está vacía, imposible extraer elementos.";
}
}
[/JAVA]

Presta atención que en pila.java defino otra clase para la excepción (PilaVacia), pero como la misma no es pública ni protected, y por lo tanto no será incluida en la documentación.

javadoc solo procesará la documentación que se escriba para atributos y métodos públicos y protegidos, salvo que por línea de comandos se ejecute -private.

Luego, desde un shell y especifícamente desde la carpeta del proyecto ejecuto: javadoc -version -author nombre_del_paquete:


[CODE]
javadoc estructuras_de_datos
Loading source files for package estructuras_de_datos...
Constructing Javadoc information...
Standard Doclet version 1.6.0_03
Building tree for all the packages and classes...
Generating estructuras_de_datos/\Nodo.html...
Generating estructuras_de_datos/\Pila.html...
Generating estructuras_de_datos/\package-frame.html...
Generating estructuras_de_datos/\package-summary.html...
Generating estructuras_de_datos/\package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
[/CODE]

Así automáticamente me crea la documentación, que luce más o menos así:

Basado en el texto original de Carlos Fontela, Orientación a objetos con Java y UML.

Tags: , ,


Leave a Reply

Your email address will not be published. Required fields are marked *