Uso de javadoc desde NetBeans

Duke, la mascota de Java, saludando

Consideracións pedagóxicas

Este material pode ser utilizado:

• No módulo Despregue de Aplicacións Web do Ciclo de Desenvolvemento de Aplicacións web
  • No "BC6. Documentación das aplicacións web e sistemas de control de versión"
    • Xeradores de doumentación integrados nas plataformas de desenvolvemento
    • Formatos estándar para a documentación. Uso de linguaxes de marcas na documentación de aplicacións web.
• No módulo Contornos de Desenvolvemento do Ciclo de Desenvolvemento de Aplicacións web

Consideracións previas

• É convinte un coñecemento básico de programación, do uso dos IDE (en particular Netbeans) e e a linguaxe Java

Instalación

• É necesaria a instalación de Netbeans:
  • Descarga da páxina oficial

Uso

Os comentarios de documentación comezan con /** e rematan con */ e poden aparecer xusto antes dunha clase, campo (variable de clase ou obxecto), construtor ou definición de método.

Dentro do comentario, a primeira parte é a descrición, seguido por cero ou máis etiquetas que comezan por @.

Documentación dunha clase

  /**
  * @author      Nome e apelidos do autor <nome@dominio.com>
  * @version     1.6  (versión actual do programa)
  * @since       1.2  (versión do paquete a partir da cal se engadiu a clase)
  */
 public class Proba {
     // corpo da clase
 }

Documentación dun método

 /**
  * Descrición curta dunha soa liña.
  * <p>
  * Descrición longa, de varias liñas,
  * de existir, iría aquí
  * <p>
  * E máis explicacións, se fixera falta 
  * en liñas sucesivas separadas por
  * parágrafos HTML
  * @param  variable Descrición do parámetro
  * @return Descrición do valor devolto.
  */
  public int nomeDoMétodo (...) {
      // Corpo do método
  }

Documentación de variables

 /**
  * Descrición da variable x.
  */
 public int x;

Documentación dun paquete

A descrición dun paquete vai nun arquivo aparte chamado package-info.java que debe atoparse no directorio do paquete e que contén a declaración do paquete, precedido inmediatamente pola descrición do mesmo.

 /**
  * paquete.subpaquete Descrición do paquete ou subpaquete.
  */
 package paquete.subpaquete;

Exemplo de uso básico

   //EXEMPLO DE PROGRAMA JAVA PARA PROBAR JAVADOC
   /**
   * Unha clase para empezar a programar en Java
   * o clásico exemplo de OlaMundo
   * @version 2.1.0, 15/10/20
   * @author Xose Programador Java 
    */
   public class holamundo {
      /** 
      * Amosa a mensaxe de Ola Mundo
      */
      public static void main(String[] args) {
          // TODO Auto-generated method stub
          System.out.println("Ola mundo!");
     }
   }

Posible tarefa

1. Documenta o código, como se fai neste exemplo dunha función que recibe un número e devolve un texto con ese número:
   1. https://www.youtube.com/watch?v=KChdcRscFt0

1. Xenera a api documentada con Javadoc
2. Cambia a plantilla de estilo por outra da túa elección:
   1. http://java-white-box.blogspot.com/2012/08/javadoc-como-personalizar-el-html.html
3. Entrega un documento explicando qué fixches e anexando a documentación xenerada nun documento comprimido.

Referencias

• Material realizado durante unha licenza de formación retribuída pola Consellería de Cultura, Educación e Ordenación Universitaria. Autoras. Amalia Falcón Docampo, Laura Fernández Nocelo e Marta Rey López. Licenza Creative Commons BY-NC-SA