Documentacin en Java: Javadoc

Programacin 2 Curso 2011/2012

Juan Manuel Gimeno Jos Luis Gonzlez

La documentacin de Java
Tanto la biblioteca estndar de Java como la de la ACM sn muy extensas
Multitud de clases Multitud de mtodos

Es imposible conocerlos todos con detalle suficiente como para utilizarlos correctamente Por ello es muy importante disponer de una muy buena documentacin.

La documentacin de Java
Es por ello que los diseadores de Java, definieron un mtodo sencillo para generar la documentacin de las clases y mtodos:
La documentacin se inserta en el mismo fichero que el cdigo (en forma de comentarios)
De esta manera es ms fcil que evolucione con l

La herramienta javadoc extrae esos comentarios especiales y genera pginas html para ser vistas desde el navegador
De esta manera facilitamos poder navegar de una clase a otra.

Accediendo a la documentacin
Como cuando configuramos las bibliotecas de la ACM aadimos el javadoc, podemos acceder a l a partir del apartado bibliotecas de nuestro proyecto Tambin podemos acceder a las de la biblioteca de Java

Aadiendo comentarios javadoc

Aadir documentacin es tan simple como poner un comentario que empiece por /** y acabe con */ Para poder estructurar mejor los comentarios dentro del comentario usaremos las marcas @param y @return para describir con detalle los parmetros y el resultado. Hay muchas marcas interesantes como por ejemplo @author, @version, @since, @throws, etc.

Cmo generarlo
Generar la documentacin en Netbeans es tan fcil como, desde el proyecto, marcar en el men contextual la opcin Generar javadoc Una vez generada, nos abrir el navegador para acceder a ella.

Accediendo al javadoc
Los ficheros generados los encontraris en el subdirectorio dist/javadoc dentro del proyecto.

Netbeans 7 y el paquete por defecto

Como ya sabis, cuando creamos una clase, aunque el Netbeans indica que no es recomendable, lo hacemos en el paquete por defecto Hasta ahora esto no daba problemas, pero a partir de la versin 7, Netbeans no genera documentacin para las clases del paquete por defecto Por eso, a partir de ahora, crearemos un paquete para todas las clases del proyecto

Creando una clase en un paquete

En vez de dejarlo en blanco aadimos un nombre para el paquete

El nombre del paquete se convierte en una subcarpeta dentro de la carpeta que contiene los ficheros java

La clase ahora pertenece al paquete

Cmo mover una clase a un paquete

Si hemos definido una clase en el paquete por defecto la podemos mover a otro paquete.

La clase principal ha de referenciar el paquete al que pertenece

Error en algunas plataformas

En algunas combinaciones de sistema operativo y versin de java, si ponemos la clase del programa principal en un paquete, al ejecutar obtenemos un error similar a:
Exception in thread "main" java.lang.UnsatisfiedLinkError: acm.util.DOSCommandLine.getLine()Ljava/lang/String; at acm.util.DOSCommandLine.getLine(Native Method) at acm.util.DOSCommandLine.getCommandLine(JTFTools.java:1627) at acm.util.JTFTools.getCommandLine(JTFTools.java:439) at acm.util.JTFTools.getMainClass(JTFTools.java:464) at acm.program.Program.main(Program.java:1320)

Error en algunas plataformas

El problema es que el mecanismo que usa la biblioteca JTF para iniciar la ejecucin de un programa es incapaz de encontrar el mtodo main Por ello lo que haremos ser incluir explcitamente un mtodo main que funcione igual que el que proporciona la biblioteca

Error en algunas plataformas

Para ello aadiramos en la clase que representa el programa principal un mtodo main como el siguiente:
package example;
import acm.program.ConsoleProgram; public class StudentTest extends ConsoleProgram { public void run() { .... } public static void main(String[] args) { new StudentTest().start(args); } }