En este taller miraremos una parte muy importante de la programación de Java: como generar documentación para nuestros programas y como revisar la documentación de las clases incluidas en en el JDK (conocido como la API).
Este es un programa que viene en el JDK, y nos permite generar el documento de ayuda de nuestras código en un formato que permite ponerlo en línea. Para ejecutar este programa, la variable de entorno PATH debe apuntar a la carpeta bin donde se encuentra el JDK. ( Por ejemplo, en mi caso tengo instalado el jdk en "C:\programs\jdk1.4.1". Entonces la variable path debe apuntar a "C:\programs\jdk1.4.1\bin". Para hacer esto en mi caso digitaria: "set PATH=%PATH%;C:\programs\jdk1.4.1\bin". Usted debe reemplazar la parte que dice C:\programs\jdk1.4.1 con la ubicación de su JDK ).
Este programa busca comentarios que comienzan con /** y terminan en */. Por ejemplo:
/**
* Clase que guarda toda la información de un evento, la fecha,
el lugar y una
* descripcion entre otros, que pertenece a una agenda.
*/
public class Evento
En este caso, antes de declarar la clase indico el objetivo de esta en el texto entre los comentarios. Por lo general, colocamos comentarios antes de la declaración de cada clase y antes de cada método y atributo que no sea privado. La primera frase de cada variable o metodo es puesta en el índice alfabético en la parte superior de la página resultante, con la descripción completa en la parte inferior. Para crear la documentación, debemos pasar por parametro el nombre de uno o mas paquetes o archivos al programa javadoc. Por ejemplo, para generar la documentación de la clase Evento del ejemplo anterior, me ubico en el directorio donde tenga guardada la clase y ejecutaría:
javadoc Evento.java
En el directorio donde ejecute javac, se crearan todos los archivos de la documentación. El archivo principal es index.html
1. Bajemos Evento.java, miremoslo y generemos la documentación para esta clase.
Existen algunos tags que nos permiten obtener ciertos efectos en la documentación. Existen tags como @param, @return y otros. Ya veremos como se utilizan, para que sirven y que obtenemos al generar la documentación.
@author : Este tag es utilizado en la documentación de la clase y especifíca el autor. Para que este tag surta efecto, se debe usar así: "javadoc -author " seguido por el nombre del archivo. Por ejemplo, para la clase Evento puede quedar así ( en mi caso partícular ):
/**
* Clase que guarda toda la información de un evento, la fecha,
el lugar y una
* descripcion entre otros, que pertenece a una agenda.
*
* @author Gabriel Lozano.
*/
public class Evento2
{
@return : indica lo que
retorna un método.
El siguiente URL provee completa documentación de la herramienta javadoc:
http://java.sun.com/j2se/javadoc/
En el sitio de java ( java.sun.com ) encontramos muchísima información del lenguaje de programación. Existen 3 plataformas de Java 2. Estas plataformas consisten en una serie de librerias escritas en Java que nos permiten hacer programas de forma mas rápida. Por ejemplo, como ya vimos, ya existe una clase que nos permite realizar ventanas de manera muy rápida ( JFrame ). Si no existieran estas librerías, tendríamos que esforzarnos en realizar mucho trabajo repetitivo ( como crear ventanas, ya que muchas aplicaciones con interfaz gráfica constan de ventanas ). Las 3 plataformas son J2SE, J2EE y J2ME. Para comenzar, debemos conocer la plataforma estandar J2SE. Podemos ver la documentación de esta plataforma y conocerla mejor por dentro.
1. Diríjase a esta dirección: http://java.sun.com/j2se/1.4.2/docs/api/index.html
Allí veremos un 'overview' de la plataforma J2SE. Revisemos su estructura.
2. Hagamos clic en donde dice javax.swing en la primera ventana pequeña en la parte superior izquierda.
3. Luego en la ventana de abajo, busquemos JFrame y hagamos clic allí.
Encontraremos toda la información de esta clase.