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