Formación informática

Java | Joomla | MySQL

Curso de Java – Tema 6: Javadoc

Persona picando códigoEn cualquier lenguaje de programación es fundamental documentar lo que hace el código. Se puede ver un gran ejemplo con la API de Java que está generada con una herramienta conocida como Javadoc que genera un conjunto de páginas HTML por las que se puede navegar usando cualquier navegador web. Lo mismo se puede generar con nuestros proyectos documentando el funcionamiento de las clases dentro del código usando los comentarios.

Al ser una página HTML podemos usar etiquetas, con su apertura y cierre, para dar formato al código que aparecerá en la misma. La más utilizada de todas es code para poner en cursiva el texto de un código Java.

Los comentarios son instrucciones especiales que no se ejecutan. Son muy útiles para los programadores en cualquier lenguaje de programación, ya que nos permite insertar anotaciones que nos servirán para aclarar trozos de código que pueden resultar confusos en un futuro. Sirven para documentar el código y explicarlo a cualquier persona que lo lea.

Todos los ejercicios del curso estarán comentados lo más extensamente para poder comprender el funcionamiento de la aplicación en cada uno de los pasos seguidos. Así que es fundamental que tengas muy presente el contenido de este artículo cuando visualices un ejercicio resuelto.

En Java existen tres maneras de comentar el código. La más sencilla es cuando queremos que un comentario sea de una línea. En este caso escribimos dos barras inclinadas (//) y el comentario a continuación; se usa para hacer anotaciones entre líneas o a continuación del código.

int edad //Variable de tipo entero que almacena la edad

Algunas veces, necesitamos escribir un comentario muy largo que ocupe varias líneas, en este escribimos /* como apertura, el comentario va a continuación, puede ocupar varias líneas y para cerrar usamos */. En caso de usar un programa IDE nos inserta las nuevas líneas de forma automática.

 /* Aplicacion que devuelve un mensaje por línea de comandos */ 

Por último tenemos un tipo de comentario especial: el Javadoc que es una utilidad de Oracle para la generación de documentación de APIs en formato HTML a partir de código fuente Java. Javadoc es el estándar de la industria para documentar clases de Java. La mayoría de los IDEs los generan automáticamente.

Javadoc también proporciona una API para crear doclets y taglets, que le permite analizar la estructura de una aplicación Java. Así es como JDiff puede generar informes de lo que ha cambiado entre dos versiones de una API.

Para generar APIs con Javadoc han de usarse etiquetas (tags) de HTML o ciertas palabras reservadas precedidas por el carácter "@". A continuación de la etiqueta se escribe el texto. El texto se escribe en la posición inmediatamente superior a lo que se quiere documentar.

Estas etiquetas se escriben al principio de cada clase, miembro o método, dependiendo de qué objeto se desee describir, mediante un comentario iniciado con "/**" y acabado con "*/".

Etiquetas de Javadoc

Tag

Descripción

Uso

Versión

@author

Nombre del desarrollador.

nombre_autor

1.0

@deprecated

Indica que el método o clase es antigua y que no se recomienda su uso porque posiblemente desaparecerá en versiones posteriores.

descripción

1.0

@param

Definición de un parámetro de un método, es requerido para todos los parámetros del método.

nombre_parametro descripción

1.0

@return

Informa de lo que devuelve el método, no se puede usar en constructores o métodos "void".

descripción

1.0

@see

Asocia con otro método o clase.

referencia (#método(); clase#método(); paquete.clase; paquete.clase#método()).

1.0

@throws

Excepción lanzada por el método

nombre_clase descripción

1.2

@version

Versión del método o clase.

versión

1.0

@exception

Nombre de la excepción más una descripción

excepciones

 
  • @author: en clases e interfaces. Se pueden poner varios. En este caso resulta apropiado hacerlo en orden cronológico.
  • @version: en clases e interfaces.
  • @param: en métodos y constructores. Se ponen tantos como argumentos tenga el constructor o método. Deberían aparecer en el mismo orden en el que se declaran.
  • @return: en métodos.
  • @excepction: en constructores y métodos. Deberían aparecer en el mismo orden en el que se declaran o en orden alfabético.
  • @throws: a partir de Javadoc 1.2 es un sinónimo de exception.
  • @see: se pueden poner varios. Se recomienda empezar por los más generales para después pasar a los más concretos.
  • @since.
  • @deprecated.

Un  ejemplo completo de clase comentado con Javadoc sería este método: 

  /**
  * Inserta un título en la clase descripción.
  * Al ser el título obligatorio, si es nulo o vacío se lanzará
  * una excepción.
  *
  * @param titulo El nuevo título de la descripción.
  * @throws IllegalArgumentException Si titulo es null, está vacío o contiene sólo espacios.

  */
 public void setTitulo (String titulo) throws IllegalArgumentException
 {
   if (titulo == null || titulo.trim().equals(""))
   {
       throw new IllegalArgumentException("El título no puede ser nulo o vacío");
   }
   else
   {
       this.titulo = titulo;
   }
 }

  

Para comentar el contenido un paquete, tenemos que crear un archivo html con el nombre package.html en dónde introduciremos el texto que documente el contenido del paquete y copiarlo en el paquete correspondiente. O mejor, crear el archivo en el paquete correspondiente. La estructura más básica de este archivo html es:

Clase principal del proyecto que ejecuta el programa

Que puedes descargar aquí en un archivo comprimido en formato zip:
Archivos:
Archivo HTML básico para comentar el contenido de un paquete.
Fecha 13-02-2018
Lenguaje  HTML
Sistema  Multi-Sistema
Tamaño del Archivo 237 B
Descargar 12

Para generar el Javadoc de nuestro proyecto, la forma más sencilla de hacerlo es hacer click derecho sobre nuestro proyecto y seleccionar en el menú desplegable Generar Javadoc para que NetBeans genere el conjunto de páginas en la carpeta dist/javadoc partiendo desde el index.html:

JavadocLa otra opción para generarlo es haciendo uso de los menús. Si lo tienes en español, tienes que ir a Ejecutar -> Generar Javadoc (nombre_del_proyecto):

Javadoc desde el menúDe cualquiera de los dos métodos, se genera el Javadoc de nuestro proyecto. Siempre que no exista algún error grave que lo impida. En este caso, Netbeans nos indicaría el error a corregir en la consola de salida. Si no se ha producido ningún error, se cargará la página principal en el navegador predeterminado de nuestro sistema operativo. Si no se carga la página principal, tendremos que abrirla manualmente. La página principal se encuentra en en la carpeta dist/javadoc de nuestro proyecto:

Carpeta principal Javadoc en WindowsEn esta carpeta tenemos todos los archivos necesarios para mostrar correctamente el Javadoc de nuestro proyecto. Así que no podemos tocar nada ni aplicar estilos propios.

Curso de Java – Tema 5: palabras reservadas <- | -> Curso de Java – Tema 7: secuencias de escape
Curso de Java - Índice ejercicios nivel básico

Escribir un comentario

Aunque los comentarios no expresan la opinión del administrador del sitio web, éste si que tiene una responsabilidad legal sobre lo que aparece. Por lo tanto, habrá una labor de moderación de los mensajes. No se permitirán mensajes ofensivos ni publicidad


Código de seguridad
Refescar

Solicitamos su permiso para obtener datos estadísticos de su navegación en esta web, en cumplimiento del Real Decreto-Ley 13/2012, de 30 de marzo. Si continúa navegando consideramos que acepta el uso de cookies. . Más información