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 por @ 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
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> */ Generales @see referencia Permite referirse a la documentación de otras clases Genera una sección See Also con enlaces HTML {@link nombre etiqueta} Similar a @see pero se puede poner dentro de una línea @since 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 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 Java javadoc bfm 5 Java javadoc bfm 6 Clases e Interfaces Todas las anteriores @version @version información sobre esta versión @author @author información sobre el autor o autores Variables Comentarios con HTML @see, @link, @deprecated @serial descripción-opcional Miembros de datos de la clase que son serializables por defecto Métodos @see, @link, @deprecated, @since @param @param nombreparámetro descripcióndelparámetro Una por parámetro @return @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 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
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 métodos 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 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
Configuración y uso de javadoc Java API (Application Programming Interface) 1 3 2 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