Tutorial escribir documentación en Java. JavaDoc

"Independientemente de la metodología que se este utilizando para el desarrollo del proyecto, es muy importante verificar que el código este correctamente comentado y documentado. Para los programas escritos en el lenguaje Java existe una convención para realizar comentarios llamada JavaDoc." 

¿Qué es JavaDoc?

El estandar "Doc" es ampliamente utilizado (no solo en Java), en casí todos los lenguajes de programación. La ventaja de utilizarlo tienen que ver con: el correcto mantenimiento del código y la obtención de documentación de manera automática.

JavaDoc es el estándar recomendado por Oracle para escribir comentarios en el código. Javadoc Tool es la herramienta para extraer y generar documentación, directamente del código en formato HTML. Para que la documentación sea en verdad útil debemos escribir los comentarios del código de acuerdo a las recomendaciones de Javadoc.

De manera general la utilidad JavaDoc, permite la extracción de todos aquellos textos o comentarios que se encuentran en el código fuente entre los caracteres /** y */.  Estos comentarios, cómo se vera con más detalle, estan en formato HTML y utilizan un conjunto de eqtiquetas o tags, para especificar información relevante a los desarrolladores y usuarios de la libreria, clase o API a la que hacen referencia.

Antes de continuar me gustaría recomendar a mis lectoras y lectores una revisión al documento Java Code Conventions ya que en el, además de las recomendaciones generales para escribir código Java de acuerdo al estandar de SUN, se encuentran también recomendaciones sobre los comentarios y la documentación del código fuente. Este archivo puede encontrarse aquí. 

Comentarios en Java

Existen dos tipos de comentarios: los comentarios de implementación y los de documentación. Los comentarios de implementación son parecidos a los que hay en C++ y se refieren a especificaciones técnicas sobre algún bloque de código o algortimo implementado en el, se encierran entre los símbolos /* y */. Los comentarios de documentación son ubicados entre los símbolos /** y */ y pueden ser extraidos a páginas HTML utilizando la herramienta JavaDoc.

Los comentarios de implementación pueden tener cuatro estilos:
1.- Comentarios de bloque, especificados entre /* (al inicio del bloque)  ... y */ (al final del bloque).
      /*
       * Este es un comentario de bloque
      */

2.- Comentarios de una sola línea. Estos se inician y terminan en una sola línea.
          if (condicion) {
              /* Este es un comentario de una sola línea */

               ...
             }

3.- Comentarios al final de una instrucción o (trailing comments).
         if (a == 2) {
              return TRUE;           /* este es un caso especial*/
         } else {
                return isprime(a);    /* trabaja en caso de que sea primo*/
         }

4.- Comentarios de final de linea o end-of-line. El comentario se inicia con los caracteres //. No debe ser utilizado en bloque para realizar comentarios de texto, pero puede ser utilizado para comentar bloques de código que deseamos no ejecutar.

if (a<2) {
    // suma = 3 + 4;
     ....
 }
 else
       return false;                    // Explica por qué aquí

Los comentarios de documentación realizan una descripción de las clases, interfaces, constructores, métodos y campos. Estos se colocan entre los delimitadores /** ... */, y deben aparecer justo antes de la declaración.

/**
 * La clase MiClase esta desarrollada para ...
 */
class MiClase { ...


Java API Specifications

API documentation (API doc) o API Specifications(Java specs) son comentarios dentro del código, que están dirigidos principalmente a los programadores.

Doc comments

Son todos aquellos comentarios delimintados por los delimitadores /** ...  */ y que son procesados por la herramienta JavaDoc para obtener una API Specification, de manera automática. 

javadoc

Es propiamente una herramienta que se encuentra dentro del SDK que genera API docs de los doc comments. 

¿Cómo escribir Doc Comments?

Un doc comment esta escrito en HTML y debe colocarse antes de la declaración de una clase, un campo, un método o un constructor. Esta hecho de dos partes: una descripción seguida de un bloque de tags: 

De la imagen anterior podemos ver que cada linea dentro del comentario esta alineada con el código debajo de ella, los tags que se muestran en el ejemplo son: @param, @return y @see. El tag @link dirigirá al usuario de la documentación al recurso que se encuentra dentro de la URL. El tag @see dirigé al usuario a otro apartado de la documentación relacionado con este código. Se usa HTML como se puede obervar al hacer uso de las etiquetas <p>, para el salto de línea. 

De manera personal recomiendo el uso de los tags @Author y @Since, para especificar el programador que creo el bloque de código y la fecha. 

NOTA: Toda la información aquí descrita ha sido tomada del sitio de Oracle: How to Write Doc Comments for the Javadoc Tool

Un ejemplo de programa en Java que crea y administra usuarios en SVN a traves del SVNkit puede verse en el siguiente ejemplo: Programa Java para crear y administrar SVN. Observa con cuidado los comentarios del JavaDoc.

Espero que esta información les sea de utilidad, no olviden regalarme un click en g+ y si desean más información del tema visiten el sitio oficial de Oracle. Salud y buena suerte.