javadoc_holamundoswing

Generación automática de documentación en Java: 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.

    javadoc_holamundoswing

    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.
    Resumen
    Nombre del artículo
    Generación automática de documentación en Java: Javadoc
    Autor
    Descripción
    Este artículo muestra como utilizar Javadoc para documentar programas realizados en Java.

    Deja un comentario

    Tu dirección de correo electrónico no será publicada. Los campos necesarios están marcados *

    Puedes usar las siguientes etiquetas y atributos HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>