Generación automática de documentación en Java: Javadoc

9 años ago
Posted in:Entornos de desarrollo
0
Author: jcmoreno
Tags: documentación Java, documentar automáticamente código, documentar código, documentar programas, javadoc

Es importante tener el código comentado y la mejor de las opciones es comentar el código dentro del mismo. Otras opciones implican mantener documentos que la mayoría de las veces se quedan obsoletos y desactualizados.

En Java, el código se documenta en el mismo fichero y con una herramienta llamada Javadoc se pueden extrer los textos y comentarios de dicho código fuente y transformarlos en páginas web con formato HTML.

Los comentarios como saben los programadores de Java se insertan entre los caracteres /** y */.

Además del comentario, se pueden incluir otras etiquetas más específicas como las siguientes:

@author. Como su nombre indica, identifica al autor del código fuente.

@version. Esta etiqueta identifica la versión del código.

@return. Especifica el valor de retorno de la función o método. No hay que especificar dicha etiqueta si la función devuelve un valor void.

@since. Esta etiqueta especifica la fecha de creación del programa.

@deprecated. Especifica que esta función, método o la misma clase está obsoleta.

@param <nombre_par>. Describe el parámetro «nombre_par». Se suele especificar cada parámetro en una línea.

@see. Utiliza esta etiqueta si quieres redirigir al que lee el código a otro apartado del mismo.

@link <URL>. Utiliza esta etiqueta si quieres dirigir al usuario a una URL en concreto.

Veamos un ejemplo de documentación muy sencillo:

package holamundoswing;

/**
* clase holamundoswing
* @author Juan Carlos
* @version 1.0
* @since 06/06/2015
*
*

Esta clase corresponde a un ejemplo de holamundo con swing.

//Debemos importar todos los componentes que vamos a utilizar en nuestra
//aplicación
import java.awt.FlowLayout;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
……

Recuerda.
Para generar la documentación de la clase anterior se ha ejecutado desde línea de comandos lo siguiente:
javadoc holamundoswing.java

Tras ejecutar javadoc, el cual se puede ejecutar desde el propio IDE (NetBeans o Eclipse) o desde línea de comandos (si utilizas Geany deberás ejecutarlo de esta manera), obtenemos una serie de páginas web con la documentación de la aplicación.

JavaHelp como herramienta para generación de ayudas. .

Muchas veces es necesario o requerido que la propia aplicación tenga un menú de ayuda integrado dentro de la misma. JavaHelp es una extensión de Java que nos puede ayudar a implementarlo.

Generará una serie de ventanas basadas en ficheros XML y HTML las cuales podrán ser mostradas al usuario para ayudarle a manejar la aplicación.

Ejercicio propuesto.
Investiga JavaHelp y añade al programa holamundoswing una ventana de ayuda.

Ejercicio UML. Diagrama de secuencia. Sistema de visión artificial.

Examen UML con solución. Sistema Mazor-kos

UML. Diagrama de clases. La smart-city de Neo-Tokyo

Detectando clases y objetos en el juego del tetris

Entornos de desarrollo. Conceptos sobre objetos.

Ejercicio UML. Diagrama de estados. Sistema de visión artificial.

Resumen

Nombre del artículo

Generación automática de documentación en Java: Javadoc

Descripción