Programación - RafaC - 2005/2006

JavaDoc-


Uso de JavaDoc


1 Comentarios en Java

2 Formato de comentarios JavaDoc

3 La herramienta javadoc

4 Usando javadoc desde JCreator






1 Comentarios en Java

Los comentarios, anotaciones en el código que el compilador ignora pero son útiles para los programadores, existen en los lenguajes de programación desde el principio. Desde hace mucho tiempo se observó que en realidad los comentarios se usaban para dos propósitos diferentes:
Para explicar el propósito de sentencias o grupos de sentencias. Estos comentarios son útiles para el propio autor del código, y para otros que quieran modificar ese código.
Comentarios explicando qué hace una "pieza" cerrada de código. Estos comentarios son útiles para quien quiere utilizar esta "pieza" en su propio programa, y que por tanto está necesita saber lo qué hace, no cómo se las ha arreglado el programador para conseguir este resultado.
Al diseñar Java se distinguieron desde el principio ambas posibilidades. Para el primer tipo, comentarios "internos" se usan los caracteres // seguidos del comentario, o /* .... */ con el comentario en el lugar de los puntos suspensivos. La primera posibilidad indica que el resto de la línea, tras las dos barras, es un comentario, mientras que la segunda se usa para comentarios de más de una línea. Por ejemplo, un fragmento de código que calcula la suma 1+3+5+ ... +99 y muestra el resultado por pantalla:
int suma = 0; // al principio la suma vale 0 


// vamos sumando cada uno de los cuadrados entre 1 y 100 y acumulando el resultado
for (int i=1; i<=99; i+=2)
    suma += i;

// finalmente mostramos el resultado por pantalla
System.out.println(suma);    // ¿por cierto, que valor se mostrará por pantalla?
    
El segundo tipo, los usados para explicar qué hace un código son los llamados en Java comentarios JavaDoc, y se escriben comenzando por /** y terminando con */ , pudiendo ocupar varias líneas. Mientras que los comentarios usuales no tienen ningún formato, los comentarios JavaDoc siguen una estructura prefijada que describimos en el siguiente apartado.

2 Formato de los comentarios JavaDoc

Los comentarios JavaDoc están destinados a describir, principalmente, clases y métodos. Como están pensados para que otro programador los lea y utilice la clase (o método) correspondiente, se decidió fijar al menos parcialmente un formato común, de forma que los comentarios escritos por un programador resultaran legibles por otro. Para ello los comentarios JavaDoc deben incluir unos indicadores especiales, que comienzan siempre por '@' y se suelen colocar al comienzo de línea. Por ejemplo esta es una clase para representar números círculos (reducida al mínimo):
package figuras;

/**
 * Una clase para representar círculos situados sobre el plano.
 * Cada círculo queda determinado por su radio junto con las 
 * coordenadas de su  centro.
 * @version 1.2, 24/12/04
 * @author Rafa Caballero
 */

public class Círculo {
    protected double x,y; // coordenadas del centro
    protected double r;  // radio del círculo
    
    /** 
     * Crea un círculo a partir de su origen su radio.
     * @param x La coordenada x del centro del círculo.
     * @param y La coordenada y del centro del círculo.
     * @param r El radio del círculo. Debe ser mayor o igual a 0.
     */
    public Circulo(double x, double y, double r) {
        this.x=x; this.y = y; this.r = r;
    }   
    
    /** 
     * Cálculo del área de este círculo.
     * @return El área (mayor o igual que 0) del círculo.
     */
     public double área() {
        return Math.PI*r*r;
     }
     
     /** 
      * Indica si un punto está dentro del círculo.
      * @param px componente x del punto
      * @param py componente y del punto
      * @return true si el punto está dentro del círculo o false en otro caso.
      */
     public boolean contiene(double px, double py) {
        /* Calculamos la distancia de (px,py) al centro del círculo (x,y),
           que se obtiene como raíz cuadrada de (px-x)^2+(py-y)^2 */
        double d = Math.sqrt((px-x)*(px-x)+(py-y)*(py-y));
        
        // el círculo contiene el punto si d es menor o igual al radio
        return  d <= r;
     }
}
Como se ve, y esto es usual en JavaDoc, la descripción de la clase o del método no va precedida de ningún indicador. Se usan indicadores para el número de versión (@version), el autor (@author) y otros. Es importante observar que los indicadores no son obligatorios; por ejemplo en un método sin parámetros no se incluye obviamente el indicador @param. También puede darse que un comentario incluya un indicador más de una vez, por ejemplo varios indicadores @param porque el método tiene varios parámetros. Vamos a hacer un resumen de los indicadores más usuales:
@author nombreDelAutor descripción.
Indica quién escribió el código al que se refiere el comentario. Si son varias personas se escriben los nombres separados por comas o se repite el indicador, según se prefiera. Es normal incluir este indicador en el comentario de la clase y no repetirlo para cada método, a no ser que algún método haya sido escrito por otra persona.
@version númeroVersión descripción.
Si se quiere indicar la versión. Normalmente se usa para clases, pero en ocasiones también para métodos.
@param nombreParámetro descripción.
Para describir un parámetro de un método.
@return descripción.
Describe el valor de salida de un método.
@see nombre descripción. Cuando el trozo de código comentado se encuentra relacionada con otra clase o método, cuyo nombre se indica en nombre.
@throws nombreClaseExcepción descripción. Cuando un método puede lanzar una excepción ("romperse" si se da alguna circunstancia) se indica así.
@deprecated descripción. Indica que el método (es más raro encontrarlos para una clase) ya no se usa y se ha sustituido por otro.

Observación : JavaDoc es mucho más completo de lo que hemos descrito en este primer vistazo. Por ejemplo, además de para clases y métodos, también existen comentarios JavaDoc para paquetes. Los interesados pueden consultar la ayuda de Java.


3 La herramienta javadoc

Hemos visto cuál es el formato de los comentarios JavaDoc. Aparte de obtenerse comentarios más fáciles de leer para otros programadores debido al formato impuesto por los indicadores, la principal utilidad de estos comentarios es que pueden utilizarse para generar la documentación de los programas. Para ello se utiliza la herramienta javadoc parte de JDSK. El formato más sencillo de esta herramienta, cuando se emplea desde línea de comandos es:
javadoc fichero.java
Por ejemplo:
javadoc Círculo.java
Lo que hace esta herramienta es extraer los comentarios JavaDoc contenidos en el programa Java indicado y construir con ellos ficheros .html que puede servir como documentación de la clase. Por ejemplo, esta es el fichero Círculo.html que genera javadoc (entre otros) al procesar el fichero Círculo.java (para distinguirlo de este documento muestro el fondo en color, aunque en realidad es blanco):



figuras
Class Círculo

java.lang.Object
  extended by figuras.Círculo

public class Círculo
extends java.lang.Object

Una clase para representar círculos situados sobre el plano. Cada círculo queda determinado por su radio junto con las coordenadas de su centro.


Constructor Summary
Círculo(double x, double y, double r)
          Crea un círculo a partir de su origen su radio.
 
Method Summary
 double área()
          Cálculo del área de este círculo.
 boolean contiene(double px, double py)
          Indica si un punto está dentro del círculo.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Círculo

public Círculo(double x,
               double y,
               double r)
Crea un círculo a partir de su origen su radio.

Parameters:
x - La coordenada x del centro del círculo.
y - La coordenada y del centro del círculo.
r - El radio del círculo. Debe ser mayor o igual a 0.
Method Detail

área

public double área()
Cálculo del área de este círculo.

Returns:
El área (mayor o igual que 0) del círculo.

contiene

public boolean contiene(double px,
                        double py)
Indica si un punto está dentro del círculo.

Parameters:
px - componente x del punto
py - componente y del punto
Returns:
true si el punto está dentro del círculo o false en otro caso.




Como se ve, es un fichero muy completo, y con un aspecto agradable, generado sin apenas esfuerzo. En caso de que nuestra aplicación contenga varias clases la herramienta se encarga de generar ficheros índice y de establecer los enlaces entre todas ellas. La herramienta es, por tanto fundamental en el desarrollo en Java, aunque durante el curso no la usaré apenas al hacer tan sólo programas "de juguete".

Aviso: Un programa mal documentado es, básicamente, un programa inútil. Esto es así porque los programas no son nunca productos cerrados, acabados; siempre se encuentran errores que corregir, posible ampliaciones. Y el código que nos parece evidente un día se convierte en críptico e inmanejable una semana después. La herramienta javadoc ayuda a mantener la documentación del código en un formato legible y práctico.


4 Usando javadoc desde JCreator

Si tenemos instalado el compilador Eclipse la herramienta javadoc está directamente accesible. Si en cambio tenemos JCreator (siempre más espartano) no tendremos acceso directo a javadoc, pero podemos configurar el entorno para crear dicho acceso. Vamos a ver como se hace.
* Dentro del menú Configure elegir la opción Options .

* En la ventana que aparece, hacemos click sobre la palabra Tools que aparece en la lista de la izquierda. La pantalla tendrá el aspecto:

tools


* Pulsar el botón New y del menú desplegable que aparece elegir la primera opción, Dos Command . En la ventana que aparece nos pregunta el nombre del comando (Dos Command:) escribiremos, por ejemplo: javadoc .

* Ahora a la palabra tools a la izquierda de la ventana debe tener una subopción con el nombre javadoc . Hacer click sobre esta subopción (aparece enmarcada en un círculo en la figura de abajo). Nos cambiará el lado derecho de la ventana para que introduzcamos los datos de llamada a la herramienta. Al lado de "Arguments:" escribir javadoc.exe -d "$[PrjDir]" $[JavaFiles] , y al lado de "Initial directory:" $[JavaHome]\bin . El aspecto final será:

tooldoc

Ahora pulsamos el botón "OK" y ya tenemos el acceso a javadoc listo. Para usarlo sólo hay que pulsar Ctrl+1 , o hacer click sobre la llave inglesa marcada con 1. Al hacerlo se llamará a javadoc para todos los ficheros java del proyecto. Para poder además ver los ficheros generados podemos añadir otra herramienta más, como se describe en el punto siguiente.

* Repetimos el proceso anterior para crear un nuevo acceso a herramientas (Configure+Options, pulsar sobre Tools, pulsar sobre el botón New y elegir la primera opción "Dos Command"). Cuando salga la ventana pidiendo el dato "Dos Command" introducimos el texto explorer "$[PrjDir]\index.html" Pulsamos a continuación OK, y ya tenemos listo en Ctrl+2 , o al hacer click sobre la llave inglesa marcada con 2, un acceso al fichero "index.html" generado por la herramienta javadoc (si no hubo errores y el fichero pudo generarse, claro). El fichero "index.html" contiene el índice de todos los documentos creados para las diferentes clases de la aplicación; desde él podemos hacer click sobre el nombre de la clase que deseemos en particular.

Observación: Por supuesto los pasos anteriores sólo hay que hacerlos una vez; la próxima vez que entremos en JCreator se podrán usar las herramientas directamente.




Página Principal-


2005-2006 Rafael Caballero