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:
/**
*
* @author Luciano
* @version 1.0
*
* @param <T> Objeto genéricos
*/
public class Nodo <T>{
T inf;
Nodo<T> 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<T> enlace) {
this.inf = inf;
this.enlace = enlace;
}
}
/**
*
* @author Luciano
* @version 1.0
*
* @param <T> Objeto generico
*/
public class Pila <T>{
private Nodo<T> 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<T> nuevo = new Nodo <T>(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.";
}
}
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:
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.
2 Respuestas para "Documentando con javadoc"
[...] unos días atrás comentaba lo que era javadoc y como generar la documentación utilizando la aplicación de consola javadoc provista en el [...]
No puedo generar javaDoc sin IDE.
TEngo instalado java en C:\ y mi proyecto en D:\workspace, como le hago para generar el javadoc de este sin ningun IDE, Gracias
(Avisame al mail please: dmcoding hotmail com ). GRACIAS
Comentarios: