Instrucciones de como utilizar el generador de

Universidad Simón Bolívar
Dpto. de Computación y T.I.
Documento realizado por: Lee Lima López
Carnet 97-29741
Taller de Algoritmos I
Documentación de programas en JAVA con IDOCLET
Para generar una documentación de un archivo en un formato que puede ser
interpretado con un navegador de Internet, se puede utilizar el programa javadoc o su
versión modificada llamada iDoclet.
A continuación se explica la manera de instalar la herramienta iDoclet y el
manejo de la misma.
INSTALACIÓN DE IDOCLET:
-
-
-
Para instalar iDoclet es necesario poseer Java
Son necesarios los archivos: idoclet_source.zip, examples.zip e
idoclet.jar. Estos archivos se pueden conseguir en la dirección:
http://home.sol.no/~hellesoy/idoclet.html
Una vez descomprimidos los archivos, colocarlos todos preferiblemente en un
mismo directorio (les conveniente ubicarlos dentro de la carpeta lib perteneciente
al JDK).
Es necesario modificar el archivo idoclet.bat, para especificar el directorio donde
esta instalado el JDK entre otras cosas. Para esto abrir el archivo con un editor y
cambiar lo que está en letras “negritas”, no deberá tocar el resto.
C:\jdk1.2\bin\java -mx40m -ms40m -cp
D:\prog\java\lib\iDoclet.jar;C:\jdk1.2\lib\tools.jar
com.sun.tools.javadoc.Main -private -author -version -doclet
iContract.doclet.Standard -sourcepath D:\Prog\java\JavaSource
-d D:\Prog\java\dbcdemodoc -nopost -noinvariant @packages
Los cambios se deben realizar teniendo en cuenta los siguientes aspectos en orden:
 Ubicación del JDK en su disco duro (Usualmente utilizado como C:, de no ser
esta la letra de su disco cambiarla a la letra correspondiente en cada uno de los
casos).
 Ubicación del archivo iDoclet.jar
 Ubicación
del
archivo
tools.jar
(su
ubicación
estándar
es
DISCO:\jdk(versión)\lib\ ).
 Ubicación de sus programas fuente en Java. (usualmente se crea algun
directorio para el codigo fuente, por ejemplo misProgramas)
 La ubicación que Ud. desea para los archivos en HTML generados por
iDoclet. (Puede crear un directorio en donde será colocada la documentación
generada, por ejemplo Docum).
El archivo idoclet.bat modificado sería el siguiente:
C:\jdk1.2.1\bin\java -mx40m -ms40m -cp
C:\jdk1.2.1\lib\iDoclet.jar;C:\jdk1.2.1\lib\tools.jar
com.sun.tools.javadoc.Main -private -author -version -doclet
iContract.doclet.Standard -sourcepath
C:\misProgramas\ -d C:\misProgramas\docum -nopost -noinvariant
@packages
Es necesario que coloque toda la información del anteriormente mostrada en una
misma línea en el editor donde lo realice.
-
-
-
Debe cerciorarse que el archivo packages se encuentra en el mismo directorio de
iDoclet.
El archivo packages debe ser editado para que contenga los nombres de los
programas a los cuales se les desea generar la documentación. Debe sustituir
iContract.doc.tutorial.Person, que hace referencia al archivo de ejemplo,
por la dirección del documento que desea ejecutar (separando con puntos y no con
“\” como es costumbre).
Por ultimo ejecutar desde el mismo directorio donde se encuentra el iDoclet,
colocando :
idoclet. (desde la línea de comando).
En caso de que obtenga un mensaje indicando que el sistema no ha conseguido
alguno de los archivos necesarios para la ejecución del idoclet, deberá modificar
el archivo
MANEJO DE IDOCLET:
Para realizar la documentación de rutinas en Java es necesario utilizar
inicialmente:
/** para abir el bloque de documentación y
*/ para cerrarlo
Una vez utilizados los caracteres de documentación, Idoclet posee una serie de
palabras clave que se pueden utilizar internamente en el bloque. A continuación
nombraremos las palabras claves más usadas como:
@pre
el cual permite declarar las precondiciones.
@post
permite declarar las postcondiciones.
@param para describir los parámetros de la función.
@return para describir las variables de salida de la función.
@author para indica el nombre del autor del código o proyecto.
@version para indicar la versión del proyecto.
@invariant indica los elementos invariantes de una función.
@see
para hacer referencia a otras clases asociadas a la que se esta señalando.
Por ejemplo:
/**
*Dibuja una línea recta entre dos puntos especificados en
la máquina de trazados.
*@pre |x1| <= this.XMAX ^ |y1| <= this.XMAX ^
|x2| <= this.XMAX ^ |y2| <= this.XMAX
*@post hayLinea(this, x1, y1, x2, y2)
*/
void dibujarLinea(int x1, int y1, int x2, int y2)
{
:
:
}
/**
* METODO duplicar
* DEFINICION: duplica un valor determinado
* @param: entero x.
* @return: el entero duplicado
*/
public void duplicar(int x)
{
int i;
i = 2*x;
return(i);
}