Java javadoc bfm 1

Documentacin de programas: javadoc

Java javadoc bfm 2
Documentacin de programas Java
En el diseo del lenguaje se ha tenido en cuenta la
documentacin de los programas y el mantenimiento de
dicha documentacin
La documentacin y el cdigo se incluyen dentro del mismo
fichero
Tipo de comentario especfico para documentar
/** Comentario de documentacion */
Inclusin de una herramienta para la extraccin de la
documentacin --> javadoc
Generacin de documentacin en HTML
Este principio se ha aplicado al propio lenguaje de modo
que la documentacin de la API se ha generado con
javadoc
Java javadoc bfm 3
Uso de javadoc
Dos modos de uso
Inclusin de texto con formato HTML en los comentarios de
documentacin
Utilizacin de la etiquetas de documentacin
Estas etiquetas empiezan por @ y se colocan al principio de la lnea
aunque pueden tener un * inicial que se ignora
Los comentarios deben aparecer inmediatamente antes de
los elementos a comentar
La primera frase de cada comentario de documentacin debe
ser un resumen que contenga una descripcin completa y
concisa de la entidad declarada.
Se deben comentar por lo menos los elementos pblicos y
protegidos
Java javadoc bfm 4
Ejemplo
Elementos a comentar
Clases e Interfaces
Variables
Mtodos
/** Comentario de la clase docTest
* este comentario puede tener varias lneas
* en cuyo caso se suelen incluir estos asteriscos iniciales*/
public class PruebaDeDocumentacion {
/** Comentario de la variable numero */
public int numero;
/** Comentario del metodo prueba */
public void prueba() {}
}
Comentario de una clase y todos sus elementos pblicos
Java javadoc bfm 5
Ejemplo del uso de HTML
Dentro de los comentarios de documentacin se pueden
incluir cdigos de formato HTML
No usar cabeceras (p.e. <h1>) o separadores (p.e. <hr>)
/**
* Se puede <em>incluso</em> insertar una <b>lista </b>:
* <ol>
* <li> Elemento uno
* <li> Elemento dos
* <li> Elemento tres
* </ol>
*/
Java javadoc bfm 6
Etiquetas de documentacin
Generales
@see referencia
Permite referirse a la documentacin de otras clases
Genera una seccin See Also con enlaces HTML
{@link nombre etiqueta}
Similar a @see pero se puede poner dentro de una lnea
@since texto
En el texto se indica desde cuando est disponible esta caracterstica
Paquetes
Todas las anteriores. Esta documentacin se incluye en un
fichero denominado package.html
@deprecated
@deprecated comentario de mtodos obsoletos y que por tanto no se
deberan utilizar
Se debe indicar desde que versin est obsoleto y que se debe usar ahora
Java javadoc bfm 7
Etiquetas de documentacin
Clases e Interfaces
Todas las anteriores
@version
@version informacin sobre esta versin
@author
@author informacin sobre el autor o autores
Variables
Comentarios con HTML
@see, @link, @deprecated
@serial descripcin-opcional
Miembros de datos de la clase que son serializables por defecto
Java javadoc bfm 8
Etiquetas de documentacin
Mtodos
@see, @link, @deprecated, |@since
@param
@param nombreParmetro descripcinDelParmetro
Una por parmetro
@return
@return descripcin significativa del resultado devuelto
@throws (desde Java 1.2, antes se utilizaba @exception )
@exception nombreCompletoExcepcin descripcin
@ throws nombreCompletoExcepcin descripcin
@deprecated
@serialData
Si la clase implementa mtodos de serializacin describe los datos que
se almacenan o se leen mediante los mtodos writeObject() y
readObject() respectivamente
Java javadoc bfm 9
Etiqueta @see
Tiene diversas formas
@see "string" (falla en java 1.2)
@see <a href="URL#valor">etiqueta</a>
@see paquete.clase#miembro etiqueta
En general las referencias pueden ser
Miembros o mtodos de la misma clase
@see #miembro
@see #metodo(Tipo, Tipo,...)
Clases (o miembros de la clases) del mismo paquete o de
paquetes importados
see Clase#miembro
Referencias a otros paquetes
@see paquete.Clase#metodo(Tipo, Tipo,...)
Java javadoc bfm 10
Uso de javadoc
La utilidad de documentacin javadoc es un programa que
se suministra dentro de la distribucin de J2SE
Modo de uso
Javadoc [opciones] [paquetes] [archivosFuente] [@ficheros]
[opciones]
Modifican el funcionamiento de javadoc (hay mas de 40
opciones consultar el API)
Se pueden averiguar mediante javadoc help
Ejemplos
javadoc author version private *.java
Produce documentacin en el directorio actual de todos los ficheros java
considerando todos los elementos (incluidos los privados) con
informacin de autor y versin
Java javadoc bfm 11
Mas ejemplos
javadoc author version private d .\documentos *.java
Produce documentacin en el subdirectorio documentos de
todos los ficheros java considerando todos los elementos
(incluidos los privados) con informacin de autor y versin
Java javadoc bfm 12
Jcreator creacin de una JDK tool
Java javadoc bfm 13
Configuracin y uso de javadoc
1
2
3
Java javadoc bfm 14
Java API (Application Programming Interface)
Java javadoc bfm 15 Java javadoc bfm 16
Java javadoc bfm 17
Paquete es.ucm.esi
Java javadoc bfm 18
Paquete es.ucm.esi
Java javadoc bfm 19
Paquete es.ucm.esi