Documentación de programas Java. Documentación de programas: javadoc. Uso de javadoc. Ejemplo

Transcripción

1 Documentación de programas Java Documentación de programas: javadoc Java javadoc bfm 1 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 /** 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 2 Uso de javadoc 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 Estas etiquetas empiezan y se colocan al principio de la línea 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 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 Java javadoc bfm 3 Ejemplo 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 { /** Comentario de la variable numero */ public int numero; /** Comentario del metodo prueba */ public void prueba() {} } Java javadoc bfm 4

2 Ejemplo del uso de HTML 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>) /** * Se puede <em>incluso</em> insertar una <b>lista </b>: * <ol> * <li> Elemento uno * <li> Elemento dos * <li> Elemento tres * </ol> */ referencia Permite referirse a la documentación de otras clases Genera una sección See Also con enlaces HTML {@link nombre etiqueta} Similar pero se puede poner dentro de una texto En el texto se indica desde cuando está disponible esta característica Paquetes Todas las anteriores. Esta documentación se incluye en un fichero 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 Java javadoc bfm 5 Java javadoc bfm 6 Clases e Interfaces Todas información sobre información sobre el autor o autores Variables Comentarios descripción-opcional Miembros de datos de la clase que son serializables por nombreparámetro descripcióndelparámetro Una descripción significativa del resultado (desde Java 1.2, antes se nombrecompletoexcepción throws 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 7 Java javadoc bfm 8

3 Tiene diversas "string" (falla en java <a paquete.clase#miembro etiqueta En general las referencias pueden ser Miembros o métodos de la misma #metodo(tipo, Tipo,...) Clases (o miembros de la clases) del mismo paquete o de paquetes importados see Clase#miembro Referencias a otros paquete.clase#metodo(tipo, Tipo,...) Java javadoc bfm 9 Uso de javadoc 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 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 Mas ejemplos 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

4 Configuración y uso de javadoc Java API (Application Programming Interface) Java javadoc bfm 13 Java javadoc bfm 14 Java javadoc bfm 15 Java javadoc bfm 16

5 Paquete es.ucm.esi Paquete es.ucm.esi Java javadoc bfm 17 Java javadoc bfm 18 Paquete es.ucm.esi Java javadoc bfm 19