Java doc

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.

---

---

---