Java doc genera documentación API en formato HTML para el paquete especificado o para las clases individuales en Java. También se puede indicar una serie de paquetes o clases Java con los que se desea generar la documentación. Java doc genera un archivo .html por cada clase .java y paquete que encuentra. También genera la jerarquía de clases en un archivo denominado tree.html y un índice con todos los miembros que ha detectado en un archivo denominado AllNames.html.
Para generar la documentación, se debe utilizar la aplicación javadoc que se encuentra en la ruta
[jdk]/bin/javadoc [nombrePaquete] | [archivos.java]
En donde la ruta [jdk] representa la ubicación donde se encuentra instalada la maquina virtual de Java. El parámetro [nombrePaquete] hace referencia al paquete al que se le aplicara javadoc y el parámetro [archivo.java] hace referencia a la clase a la que se le aplicara javadoc
Se puede configurar el contenido y el formato de salida que se va a generar con javadoc a través de doclets. Un doclet es un programa Java escrito utilizando el Java Doclet API, que especifica el contenido y formato de la salida que ha de generar javadoc. Se pueden escribir doclets para generar cualquier tipo de salida de texto, ya sea HTML, SGML, RTF o MIF.
Cuando no se indica ningún doclet específico en la línea de comandos, javadoc utilizará el doclet estándar que genera una salida HTML.
DOCUMENTACIÓN DE CÓDIGO FUENTE
Para generar el Java Doc no es necesario hacer comentarios a todas las líneas de código. Lo único estrictamente necesario es comentar la clase y cada uno de sus métodos. Como javadoc comprueba automáticamente clases, interfaces, métodos y atributos, se puede añadir documentación adicional a través de comentarios de documentación en el código fuente.
Java doc reconoce marcas especiales cuando recorre los comentarios de documentación. Estas marcas permiten autogenerar una documentación completa y bien formateada del API a partir del código fuente. Las marcas comienzan siempre con el signo @. Estas marcas deben situarse al principio de la línea y todas las marcas con el mismo nombre deben agruparse juntas dentro del comentario de documentación. Solamente se indicarán las más representativas agrupadas por clases, métodos y atributos.
Para documentar clases e interfaces se cuenta con las siguientes etiquetas:
@version 1.0
Incluye información de versión de la clase. Un comentario de documentación puede incluir más de una marca @version.
@author El nombre del autor
Incluye información de versión de la clase. Un comentario de documentación puede incluir más de una marca @author.
@see java.lang.String
Incluye un enlace a la documentación de una clase a la clase en la zona “See Also”. Un comentario de documentación puede incluir más de una marca @see.
@see java.lang.String#valueOf
El carácter # separa el nombre de una clase del nombre de uno de sus atributos o métodos.
Para documentar métodos se cuenta con las siguientes etiquetas:
@param parametro descripcion
Incluye información de parámetro del método. Cada método debe incluir tantas etiquetas como parámetros
@return descripcion
Incluye información de retorno del método.
@exception nombre de la clase de Excepcion descripcion
Incluye información de manejo de excepción que puede ser lanzada por el método. La excepción estará enlazada con su clase en la documentación.
RESULTADOS DE JAVA DOC
Considerando la implementación de figuras geométricas presentadas en el capitulo anterior, se puede generar la siguiente documentación.
Clase FiguraGeometrica
package FigurasGeometricas;
/**
* Clase abstracta que hereda a Circulo, Cuadrado, Triangulo y Rectangulo
* @version 1.0
* @author Hector Florez
*/
public abstract class FiguraGeometrica {
protected double valor1;
/**
* Constructor. Asigna un valor a la figura geometrica
* @param valor1 Recibe valor del atributo a traves del constructor
*/
public FiguraGeometrica(double valor1) {
super();
this.valor1 = valor1;
}
/**
* Metodo consultor del atributo valor1
* @return Retorna el valor del atributo a traves del metodo consultor
*/
public double getValor1() {
return valor1;
}
/**
* Metodo modificador del atributo valor1
* @param valor1 Recibe valor del atributo a traves del metodo modificador
*/
public void setValor1(double valor1) {
this.valor1 = valor1;
}
/**
* Metodo abstracto que define el servicio calcular area
* @return Retorna el area de la figura
*/
public abstract double getArea();
/**
* Metodo abstracto que define el servicio calcular perimetro
* @return Retorna el perimetro de la figura
*/
public abstract double getPerimetro();
}
Clase Circulo
package FigurasGeometricas;
/**
* Clase que provee servicios para el TAD Circulo
* @version 1.0
* @author Hector Florez
* @see Math
*/
public class Circulo extends FiguraGeometrica {
/**
* Constructor. Asigna un valor al circulo.
* Llama al constructor de FiguraGeometrica
* @param valor1 Recibe valor del atributo a traves del constructor
*/
public Circulo(double valor1) {
super(valor1);
}
/**
* Metodo sobre-escrito que calcula el area del circulo
* @return Retorna el area del circulo
*/
@Override
public double getArea() {
return Math.PI*Math.pow(this.valor1, 2);
}
/**
* Metodo sobre-escrito que calcula el perimetro del circulo
* @return Retorna el perimetro del circulo
*/
@Override
public double getPerimetro() {
return Math.PI*this.valor1;
}
}
Documentando todas las clases del paquete FigurasGeometricas, al aplicar javadoc, se obtienen los siguientes resultados.
