Documentación en Java:

Javadoc

Programación 2 – Curso 2011/2012

Juan Manuel GimenoJosé Luis González

La documentación de Java

• Tanto la biblioteca estándar de Java como la

de la ACM sn muy extensas

– Multitud de clases

– Multitud de métodos

• Es imposible conocerlos todos con detalle

suficiente como para utilizarlos correctamente

• Por ello es muy importante disponer de una

muy buena documentación.

La documentación de Java

• Es por ello que los diseñadores de Java, definieron un método sencillo para generar la documentación de las clases y métodos:

– La documentación se inserta en el mismo fichero que el código (en forma de comentarios)

• De esta manera es más fácil que evolucione con él

– La herramienta javadoc extrae esos comentarios especiales y genera páginas html para ser vistas desde el navegador

• De esta manera facilitamos poder navegar de una clase a otra.

Accediendo a la documentación

• Como cuando configuramos las bibliotecas de la ACM añadimos el javadoc, podemos acceder a él a partir del apartado bibliotecas de nuestro proyecto

• También podemos acceder a las de la biblioteca de Java

Añadiendo comentarios javadoc

• Añadir documentación 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 parámetros y el resultado.

• Hay muchas marcas interesantes como por ejemplo @author, @version, @since, @throws, etc.

Cómo generarlo

• Generar la documentación en Netbeans es tan fácil como, desde el proyecto, marcar en el menú contextual la opción “Generar javadoc”

• Una vez generada, nos abrirá el navegador para acceder a ella.

Accediendo al javadoc

• Los ficheros generados

los encontraréis en el

subdirectorio

dist/javadoc dentro del

proyecto.

Netbeans 7 y el paquete por defecto

• Como ya sabéis, 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 versión 7, Netbeans no genera documentación 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

añadimos 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

Cómo 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 versión 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 ejecución de un

programa es incapaz de encontrar el método

main

• Por ello lo que haremos será incluir

explícitamente un método main que funcione

igual que el que proporciona la biblioteca

Error en algunas plataformas

• Para ello añadiríamos en la clase que

representa el programa principal un método

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);

}

}