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

Documentacin de programas: javadoc

/** 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 1 Java javadoc bfm 2

Uso de javadoc
Dos modos de uso Inclusin de texto con formato HTML en los comentarios de documentacin Utilizacin de la etiquetas de documentacin

Ejemplo
Elementos a comentar
Clases e Interfaces Variables Mtodos

Estas etiquetas empiezan por @ y se colocan al principio de la lnea aunque pueden tener un * inicial que se ignora

Comentario de una clase y todos sus elementos pblicos

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 3

/** 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() {} }
Java javadoc bfm 4

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

Etiquetas de documentacin
Generales @see referencia

Permite referirse a la documentacin de otras clases Genera una seccin See Also con enlaces HTML Similar a @see pero se puede poner dentro de una lnea En el texto se indica desde cuando est disponible esta caracterstica

{@link nombre etiqueta}

/** * Se puede <em>incluso</em> insertar una <b>lista </b>: * <ol> * <li> Elemento uno * <li> Elemento dos * <li> Elemento tres * </ol> */
Java javadoc bfm 5

@since texto

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

Etiquetas de documentacin
Clases e Interfaces Todas las anteriores @version

Etiquetas de documentacin
Mtodos @see, @link, @deprecated, |@since @param

@version informacin sobre esta versin @author informacin sobre el autor o autores

@author

@param nombreParmetro descripcinDelParmetro Una por parmetro @return descripcin significativa del resultado devuelto @exception nombreCompletoExcepcin descripcin @ throws nombreCompletoExcepcin descripcin

@return

Variables Comentarios con HTML @see, @link, @deprecated @serial descripcin-opcional

@throws (desde Java 1.2, antes se utilizaba @exception )

Miembros de datos de la clase que son serializables por defecto

@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 8

Java

javadoc

bfm

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

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

@see #miembro @see #metodo(Tipo, Tipo,...)

Clases (o miembros de la clases) del mismo paquete o de paquetes importados

see Clase#miembro @see paquete.Clase#metodo(Tipo, Tipo,...)

Java javadoc bfm 9

Referencias a otros paquetes

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 10

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

Jcreator creacin de una JDK tool

Java

javadoc

bfm

11

Java

javadoc

bfm

12

Configuracin y uso de javadoc

1 3

Java API (Application Programming Interface)

Java

javadoc

bfm

13

Java

javadoc

bfm

14

Java

javadoc

bfm

15

Java

javadoc

bfm

16

Paquete es.ucm.esi

Paquete es.ucm.esi

Java

javadoc

bfm

17

Java

javadoc

bfm

18

Paquete es.ucm.esi

Java

javadoc

bfm

19