Tutorial de Javadoc

Carlos Proal Aguilar

*Directorio de archivos fuente
*Javadoc generado
*Presentación en PDF
1a. Parte *Paquetes
2a. Parte *Javadoc

Packages

Cuestionamiento iniciales:

- Qué pasaría si tuviéramos todos los archivos de nuestro disco duro revueltos ?
- Qué sucedería sin son nuestras clases en Java las que están en esa condición ?
- Solución: agruparlas en pequeños conjuntos conocidos como directorios.

- Definición: son grupos de clases relacionadas entre sí, ordenadas en una estructura jerárquica..

Nota: Son similares a las librerías en otros lenguajes.

Requisitos para usar paquetes:

- Cada paquete ocupa un directorio en el sistema de archivos
- La primer línea de código debe contener la frase "package" seguida del nombre del paquete.
- Para usar una clase del paquete, traerla con " import paquete.clase ".
- Si se quiere utilizar todo el paquete emplear " import paquete.* ".
- Para compilar usar jerarquías inferiores o bien incluir en el Classpath la ruta del paquete
setenv PAQUETES $HOME2/Packages
setenv CLASSPATH .:$PAQUETES

Problemas en el manejo de paquetes:

Importación entera de paquetes. import RefTeX.*; ya no es problema puesto que tenemos mucha memoria
Desperdicio en Ancho de Banda. import RefTeX.*; problema viajar archivos por la red
la solución es utilizar Jar files
Utilizar clases con el mismo nombre. import HuSeeker.*;
import HuProcessor.*
si cada paquete tiene una clase "Search", existirán coliciones; tener control.
Nombramiento :( A nivel internacional no repeticiones a través del DNS invertido
ej: com.sun.swing , mx.udlap.xtract

Especificadores de Acceso para métodos
 

public Accesible para todos sin restricciones.
protected Accesible para clases del mismo paquete.
friendly Solo para la misma clase y para aquellas que la hereden. Usado por default 
si no se especifica lo contrario.
private El más estricto, solo permite acceso desde la misma clase.
private protected

Unicamente dentro de la misma clase y subclases, pero no para el resto del
paquete y mucho menos para otros. Detalle:

Clases y Subclases pueden invocar métodos de este tipo, pero no sus instancias, ejemplo:

class Reference{
private protected String getID(int number){ ...}
}

class Multireference extends Reference{
Vector getTitles(....)
{ Reference card=new Reference();
String ID=super.getID(5); // valido
String ID=card.getID(5); // invalido
}
}

Cuadro de Especificadores de Acceso

  Especificador
Disponibilidad  
public protected friendly private private protected
clase x x x x x
subclase x x x - x
paquete x x x - -
otro paquete x - - - -
subclase otro
paquete		 x x - - x



  Regresar al inicio
 

Javadoc

Definición:

Herramienta de documentación enfocada a programas realizados en el lenguaje Java, la cual es semiautomática al facilitar la generación de un grupo de archivos HTML en base a una sintáxis de comentarios insertados en el código fuente.

Componentes:

- API : com.sun.javadoc llamado Doclet -> documentos "Doclets"
- Aplicación Javadoc

Productos Similares

- CCDOC TOOL: Herramienta muy similar que sirve para documentar programas en C++ siguiendo la misma sintáxis; disponible en http://www.joelinoff.com/ccdoc .

- DOC++: Sistema de Documentación para C/C++ y Java, proporcionando la salida en HTML o LaTeX, disponible en: http://www.zib.de/Visual/software/doc++/index.html

 

Sintáxis general

- Delimitadores: /** , */
- Código HTML
- Tags comenzando con @
- Opciones de ejecución

Tags
 

@author name-text Agrega el campo de "Author" así como el valor indicado en name-text.
@deprecated deprecated-text
Agrega un comentario indicando que el API ya no será utilizado en subsecuentes versiones.
@exception class-name description
Sinónimo de @throws.
@throws class-name description Nombre y descripción de la excepción arrojada.
{@link name label} Inserta una liga hacia la referencia espeficada en name.
javadoc {@link #getID(int) getID}
html <a href="Reference.html#getID(int)">getID</a>
página getID
@param parameter-name descrip. Agrega un parámetro a la sección del mismo nombre.
@return description Describe el valor de regreso del método en cuestión
@see reference Referencia a otra información relacionada 
@see "RefTeX" "RefTeX"
@see <a href="RefTeX.html">RefTeX</a> RefTeX
package.class#member etiqueta
@see RefTeX.Reference#getID(int) Reference		 Reference 
@since since-text Ningún efecto especial, solo indica desde cuando existe respecto a version, fecha, etc. @since JDK1.1
@version version-text Generalmente usado para indicar versión del programa o paquete, pero también puede ser usado en clases o métodos
@serial field-description Utilizado para objetos serializables

 

Ejemplo 1:

/*
* @(#)Jillustra.java 2.0 26/04/98
*
* Copyright (c) 1997,1998 Dragon Corporation. All Rights Reserved.
*
*/

package AnuncioClasificado;

import java.sql.*;

/**
* <P>La clase Jillustra provee al programador una serie de
* métodos útiles para la interacción con el DMBS Illustra(tm)
*
* <P>Para poder utilizar esta clase es necesario contar con el
* driver instalado. Este puede encontrarse en:
* <P><a href="http://illusion.fel.tno.nl/erwin/mijdbc/mijdbc.html">
* Informacion sobre MiJDBC</a>
*
* <P>Es importante hacer notar que si se contrata esta clase dentro
* de un Applet, este deberá ser provisto por el mismo servidor que
* contiene al DBMS Illustra(tm)
*
* @version 2.0 26/04/98
* @author Carlos Proal Aguilar
*/
public class Jillustra
{
 

Salida Ejemplo 1

public class Jillustra
extends java.lang.Object

La clase Jillustra provee al programador una serie de métodos útiles para la
interacción con el DMBS Illustra(tm)

Para poder utilizar esta clase es necesario contar con el driver instalado. Este
puede encontrarse en:

Informacion sobre MiJDBC

Es importante hacer notar que si se contrata esta clase dentro de un Applet,
este deberá ser privisto por el mismo servidor que contiene al DBMS
Illustra(tm)

Version:
2.0 26/04/98
Author:
Carlos Proal Aguilar

Ejemplo 2

/**
* Método que permite seleccionar los renglones de
* una tabla dada un condición, proyectando solo las
* columnas especificadas.
* <br>Usar despues de {@link #openConnection() openConnection}
* @param tabla Nombre de la tabla
* @param columnas Columnas a seleccionar
* @param where Condición
* @return La selección
* @exception Exception De no ser posible se generará una excepción
* @throws java.lang.exception excepcion de BD
* @see <a href="http://info.udlap.mx">UDLA</a>
* @see AnuncioClasificado.anuncioclasificado_usuario#limpiar() Limpieza
* @since version 1.0
* @version 2.0 26/04/98
* @deprecated se eliminara en siguiente version
*/
public ResultSet selecciona(String tabla,String columnas,String where)
throws Exception
{
 

Salida Ejemplo 2

selecciona

public java.sql.ResultSet selecciona(java.lang.String tabla,
                                     java.lang.String columnas,
                                     java.lang.String where)
                              throws java.lang.Exception
Deprecated. se eliminara en siguiente version
Método que permite seleccionar los renglones de una tabla dada un condición, proyectando solo las columnas especificadas.

Usar despues de openConnection
 
Parameters:
tabla - Nombre de la tabla
columnas - Columnas a seleccionar
where - Condición
Returns:
La selección
Throws:
java.lang.Exception - De no ser posible se generará una excepción
java.lang.exception - excepcion de BD
Since:
version 1.0
See Also:

UDLA, Limpieza

Ejecución

javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

Options
 

-public Despliega únicamente clases y miembros con especificador public.
-protected Muestra solo clases y miembros con identificadores protected o public. Este es por default.
-package Muestra aquellas clases y miembros que pertenezcan a los especificadores package, protected, y public.
-private Despliega todas las clases y sus miembros.
-help Despliega la ayuda online.
-1.1 Genera la documentación con la apariencia y funcionalidad utilizada en Javadoc 1.1. Ej. C:> javadoc -1.1 -help
-version Incluye el tag @version, el cual es omitido por default.
-author Incluye el tag @author, el cual es omitido por default.
-sourcepath sourcepathlist
Especifica la ruta de búsqueda de archivos fuentes (.java).
-classpath classpathlist Especifica las rutas donde Javadoc buscará por clases referenciadas
-d directory Espeficica el directorio de salida, en el cual Javadoc almacenara todos los documentos html generados. (Debe estar creado).
-doclet class Define la clase donde el doclet empezará la generación de la documentación.
-docletpath classpathlist Define la ruta del origen de la clase que buscará el doclet.


 

javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

Teniendo la siguiente estructura de archivos se muestran unos ejemplos:

C:
     +------RefTeX
              |
              +------Admin
              |
              +------User

Ejemplo simple que documenta todos los archivos en un directorio dado, reportando todas las clases y métodos.

javadoc [ options ] [ sourcefiles ]
C:\RefTeX\Admin>javadoc -d C:\home\html -private *.java

Ejemplo de documentar paquetes únicamente
javadoc [ options ] [ packagenames ]

C:\>javadoc -d C:\home\html RefTeX.User RefTeX.Admin

Ejemplo de documentar clases únicamente
javadoc [ options ] [ sourcefiles ]

C:> cd RefTeX
C:\RefTeX> javadoc -d C:\home\html RefTeXInstallShield.java Reference.java

Ejemplo utilizando @files
javadoc [ options ] [ @files ]

Contenido de archivo packages
RefTeX.User
RefTeX.Admin
 

C:\> javadoc -d apidocs @packages

C:\WINDOWS\Escritorio>javadoc -d .\AnuncioClasificado\html -private -author -ver
sion AnuncioClasificado
Loading source files for package AnuncioClasificado...
Constructing Javadoc information...
Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating .\AnuncioClasificado\html\overview-tree.html...
Generating .\AnuncioClasificado\html\index-all.html...
Generating .\AnuncioClasificado\html\deprecated-list.html...
Building index for all classes...
Generating .\AnuncioClasificado\html\allclasses-frame.html...
Generating .\AnuncioClasificado\html\index.html...
Generating .\AnuncioClasificado\html\packages.html...
Generating .\AnuncioClasificado\html\AnuncioClasificado/package-summary.html...
Generating .\AnuncioClasificado\html\AnuncioClasificado/package-tree.html...
Generating .\AnuncioClasificado\html\AnuncioClasificado/package-frame.html...
Generating .\AnuncioClasificado\html\AnuncioClasificado/anuncioclasificado_admin
.html...
Generating .\AnuncioClasificado\html\package-list...
Generating .\AnuncioClasificado\html\help-doc.html...
Generating .\AnuncioClasificado\html\stylesheet.css...

C:\WINDOWS\Escritorio>

 

  Regresar al inicio