• Documentación

Documentación

Java es un lenguaje cuya sintaxis es similar a C, C++ y Javascript. La explicaremos, por tanto, de forma rápida, empezando por los comentarios.

Los comentarios en Java son como los de C++ pero con añadidos. Tenemos el comentario que dura hasta final de línea:

// Esto es un comentario

Y el comentario que ocupa varias líneas:

/* Esto es un
comentario */

Sin embargo también tenemos un tipo especial de comentarios que procuran ayudar en la tarea de documentar nuestros programas. Todo programador sabe la pereza que da documentar nuestros programas, y por eso Java intenta ayudarnos con un tipo especial de comentarios. Es equivalente al anterior, pero se utiliza un asterisco más para empezar:

/** Esto es un comentario
que servirá para documentar nuestro programa */

La herramienta javadoc recogerá esos comentarios y los incluirá en una documentación en HTML que genera de forma automática. Dado que el resultado es HTML, se puede incluir HTML en los comentarios. Para respetar el modo de comentar de muchos programadores , un asterisco al comienzo de la línea será ignorado. También admite etiquetas especiales que comienzan por una arroba. Por ejemplo, nuestro anterior programa puede ser documentado de la siguiente forma:

/** Este es el primer programa del Curso de Java
* Simplemente escribe la frase "Hola, mundo"
* @author Daniel Rodríguez
* @version 1.0
*/
public class HolaMundo {
/** Punto de entrada a la clase y la aplicación
* @param args vector de cadenas que contiene los argumentos
* @return No devuelve valor de retorno alguno
* @exception Ninguna No lanza excepciones
*/
  public static void main(String[] args) {
    System.out.println("Hola, mundo");
  }
}

Podemos ver el resultado escribiendo la siguiente línea:

javadoc -author -version HolaMundo.java

Y viendo con el navegador el HTML resultante.

Entre las etiquetas especiales, cabe destacar que se diferencian entre etiquetas de clase (@author y @version) y etiquetas de método (@param, @return, @exception y @deprecated). Este último requiere una atención especial. No existe un único Java, pues después de la primera versión se lanzaron la 1.1 y la 1.2 (también conocida como Java 2). Algunos aspectos del Java original comenzaron a parecer obsoletos y se decidió desaconsejar su uso, pues podrían dejar de ser soportados en el futuro. Se marcaron con la etiqueta deprecated. Así pues, se permitió utilizar esa etiqueta a los programadores de clases.

Llegados a este punto, puede ser necesario comenzar a distinguir entre dos tipos de programadores. Unos son los que se dedican a programar las librerías y las clases. Suelen ser más experimentados y estar mejor pagados, son los "programadores de clases". Otros, en cambio, recogen las clases que otros han programado y las unen para realizar aplicaciones; son los "consumidores de clases". Conviene saber cual es nuestra función, pues muchas cosas no resultan necesarias o, al menos, importantes para un consumidor como, por ejemplo, todo este asunto del deprecated.