javadoc

Documentación de programas Java
• En el diseño del lenguaje se ha tenido en cuenta la
documentación de los programas y el mantenimiento de
dicha documentación
• La documentación y el código se incluyen dentro del mismo
fichero
• Tipo de comentario específico para documentar
Documentación de programas: javadoc
❏
/** Comentario de documentacion */
• Inclusión de una herramienta para la extracción de la
documentación --> javadoc
• Generación de documentación en HTML
• Este principio se ha aplicado al propio lenguaje de modo
que la documentación de la API se ha generado con
javadoc
Java
javadoc
bfm
1
Java
javadoc
Uso de javadoc
Ejemplo
• Dos modos de uso
• Inclusión de texto con formato HTML en los comentarios de
documentación
• Utilización de la etiquetas de documentación
• Elementos a comentar
❏
Clases e Interfaces
Variables
❏ Métodos
❏
Comentario de una clase y todos sus elementos públicos
/** Comentario de la clase docTest
* este comentario puede tener varias líneas
* en cuyo caso se suelen incluir estos asteriscos iniciales*/
public class PruebaDeDocumentacion {
• Los comentarios deben aparecer inmediatamente antes de
los elementos a comentar
• La primera frase de cada comentario de documentación debe
ser un resumen que contenga una descripción completa y
concisa de la entidad declarada.
• Se deben comentar por lo menos los elementos públicos y
protegidos
javadoc
bfm
2
❏
Estas etiquetas empiezan por @ y se colocan al principio de la línea
aunque pueden tener un * inicial que se ignora
Java
bfm
/** Comentario de la variable numero */
public int numero;
/** Comentario del metodo prueba */
public void prueba() {}
}
3
Java
javadoc
bfm
4
Ejemplo del uso de HTML
Etiquetas de documentación
• Dentro de los comentarios de documentación se pueden
incluir códigos de formato HTML
• No usar cabeceras (p.e. <h1>) o separadores (p.e. <hr>)
• Generales
• @see referencia
❏
❏
Permite referirse a la documentación de otras clases
Genera una sección See Also con enlaces HTML
• {@link nombre etiqueta}
❏
• @since texto
/**
* Se puede <em>incluso</em> insertar una <b>lista </b>:
* <ol>
* <li> Elemento uno
* <li> Elemento dos
* <li> Elemento tres
* </ol>
*/
Java
javadoc
bfm
Similar a @see pero se puede poner dentro de una línea
❏
En el texto se indica desde cuando está disponible esta característica
• Paquetes
• Todas las anteriores. Esta documentación se incluye en un
fichero denominado package.html
• @deprecated
@deprecated comentario de métodos obsoletos y que por tanto no se
deberían utilizar
❏ Se debe indicar desde que versión está obsoleto y que se debe usar ahora
❏
5
Java
javadoc
bfm
Etiquetas de documentación
Etiquetas de documentación
• Clases e Interfaces
• Todas las anteriores
• @version
• Métodos
• @see, @link, @deprecated, |@since
• @param
❏
❏
@version información sobre esta versión
❏
• @author
❏
❏
javadoc
bfm
@return descripción significativa del resultado devuelto
• @throws (desde Java 1.2, antes se utilizaba @exception )
❏
❏
@exception nombreCompletoExcepción descripción
@ throws nombreCompletoExcepción descripción
• @deprecated
• @serialData
Miembros de datos de la clase que son serializables por defecto
Java
@param nombreParámetro descripciónDelParámetro
Una por parámetro
• @return
@author información sobre el autor o autores
• Variables
• Comentarios con HTML
• @see, @link, @deprecated
• @serial descripción-opcional
❏
6
❏
7
Si la clase implementa métodos de serialización describe los datos que
se almacenan o se leen mediante los métodos writeObject() y
readObject() respectivamente
Java
javadoc
bfm
8
Etiqueta @see
Uso de javadoc
• 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 métodos de la misma clase
• La utilidad de documentación javadoc es un programa que
se suministra dentro de la distribución 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
❏
• Referencias a otros paquetes
❏
@see paquete.Clase#metodo(Tipo, Tipo,...)
Java
javadoc
bfm
9
Mas ejemplos
Produce documentación en el directorio actual de todos los ficheros java
considerando todos los elementos (incluidos los privados) con
información de autor y versión
Java
javadoc
bfm
10
Jcreator – creación de una JDK tool
• javadoc –author –version –private –d .\documentos *.java
• Produce documentación en el subdirectorio documentos de
todos los ficheros java considerando todos los elementos
(incluidos los privados) con información de autor y versión
Java
javadoc
bfm
11
Java
javadoc
bfm
12
Configuración y uso de javadoc
1
Java API (Application Programming Interface)
3
2
Java
javadoc
bfm
13
Java
javadoc
bfm
14
Java
javadoc
bfm
15
Java
javadoc
bfm
16
Paquete es.ucm.esi
Java
javadoc
Paquete es.ucm.esi
bfm
17
bfm
19
Paquete es.ucm.esi
Java
javadoc
Java
javadoc
bfm
18