Utilización de Comentarios

Comentarios en Java

Primeramente vale hacer mencionar los tipos de comentarios utilizados en Java, existen dos tipos de comentarios puros como tal :

 

     /* Este es un comentario que expande 
      diversas lineas, sin embargo, este 
      no será incluido en la documentación */

     //  Este es un comentario de linea únicamente
     //  Tampoco será incluido en la documentación

Los dos tipos de comentarios anteriores son utilizados como guia dentro del código fuente, esto es, a partir de ellos no son generados ningún tipo de documentación, cualquier palabra entre /* y */ es considerada comentario, al igual que todo renglón que inicie con //.

Para que un comentario sea contemplado en la generación de documentación se utiliza la siguiente sintaxis

 

/** Un comentario para Clase  */
     public class pruebaDocs {
       /** Un comentario para Variables  */
       public int i;
       /** A comentario para método  */
       public void f() {}
     }

Todo elemento colocado entre los elementos /** */ será contemplado en la generación de documentación, dependiendo de la ubicación de este comentario será generada la documentación, esto es, si aparece antes de un elemento class es considerado documentación para la Clase y así sucesivamente.

Existe otra Sintaxis especifica para definir los elementos dentro de los comentarios, la cual se ilustra a continuación:

 

import java.util.*;

     /** 
      * Programa que Despliega la Fecha. 
      * @author Juan Sanchez
      * @author jsanchez@osmosislatina.com 
      * @version 1.7 
     */
     public class PruebaFecha {
       /** Punto de Entrada único para Clase 
        * @param args Arreglo de String's
        * @return Sin valor de retorno 
        * @exception exceptions Ningún error (Excepción) definida
        */
       public static void main(String[] args) {
         System.out.println("Hoy es: ");
         System.out.println(new Date());
       }
     } 

Los elementos que inician con el símbolo @ son utilizados para indicar parámetros específicos dentro de la documentación; los anteriores son algunos elementos que pueden ser utilizados al definir documentación.

En la siguiente sección serán ilustrados otros elementos @, así como el proceso para generar la documentación HTML / XHTML del código fuente Java.