Documente su código Java automáticamente con Javadoc

Si realiza algún tipo de programación, sabrá que una de las tareas más tediosas involucradas es documentar su código. Ya sea que lo encuentre levemente molesto o una tarea que enfrenta con absoluto pavor, la documentación del código es esencial. Otros necesitan entender cómo funciona su código, ¡e incluso podría ser uno de ellos si lo lee en una fecha posterior!

Java proporciona convenientemente una solución integrada al problema: Javadoc.

Javadoc puede ayudarlo a documentar su código automáticamente

Ojalá ya lo sigas buenas prácticas de codificación e incluya comentarios explicativos en su código. Si bien este tipo de comentarios en el código es ciertamente útil, en realidad no proporciona nada comparable a un manual.

Claro, otro programador puede mirar a través de su código y leer acerca de las clases, métodos y funciones específicas que están frente a él. Sin embargo, es extremadamente difícil obtener una buena visión general de todo el código o encontrar funciones que podrían ser útiles cuando no sabes que existen. Javadoc tiene como objetivo resolver ese problema.

Javadoc generará un manual HTML detallado y fácil de leer para todo su código automáticamente. Lo mejor de todo es que lo hace mediante el uso de comentarios de código que probablemente ya estés escribiendo.

¿Qué es exactamente Javadoc y cómo funciona?

Javadoc es un programa independiente que se incluye con las versiones del kit de desarrollo de Java (JDK) de Oracle. De hecho, no puedes descargarlo por separado. Cuando descargas y instalar una de las versiones JDK de Oracle, también instalará Javadoc.

Cuando lo ejecuta, Javadoc genera documentación HTML a partir de comentarios con formato especial en su código fuente de Java. Este proceso crea una documentación más útil y legible al mismo tiempo que fomenta las mejores prácticas.

En pocas palabras, Javadoc le permite escribir su código y su documentación al mismo tiempo. Simplifica su flujo de trabajo y le permite hacer un uso más eficiente de su tiempo.

Javadoc funciona analizando comentarios con formato especial en su código y convirtiéndolos en salida HTML. El único cambio que realmente necesita hacer es incluir ciertas cadenas en sus comentarios. Estos permiten que Javadoc sepa lo que desea incluir en la documentación final.

Los comentarios de Javadoc deben preceder inmediatamente a una declaración de clase, campo, constructor o método. El comentario en sí debería:

• Comienza con los tres personajes. /**.
• Incluya un asterisco al comienzo de cada nueva línea.
• Cerrar con los dos personajes. */.

Dentro de los comentarios, puede incluir HTML en el resultado final e incluir etiquetas que generarán enlaces a partes relevantes de su base de código. Incluso puede usar cosas como etiquetas de imagen HTML para incluir imágenes en la documentación final. Una vez que se acostumbre al formato y las etiquetas disponibles, escribir dichos comentarios es muy sencillo.

Aquí hay un ejemplo para ilustrar comentarios simples de Javadoc que describen una función que obtiene una imagen de una URL y la imprime en la pantalla. El comentario precede inmediatamente a la función y describe lo que hace. Este bloque de comentarios también utiliza tres etiquetas específicas de la sección: @param, @devolver, y @ver.

/**
* Devuelve un objeto Imagen que luego se puede pintar en la pantalla.
* El argumento url debe especificar un absoluto {@Enlace dirección URL}. El nombre
* argumento es un especificador que es relativo al argumento url.
* 

* Este método siempre regresa inmediatamente, ya sea que el
* la imagen existe. Cuando este applet intenta dibujar la imagen en
* la pantalla, se cargarán los datos. Las primitivas gráficas
* que dibuje la imagen se pintará de forma incremental en la pantalla.
*
* @param url una URL absoluta que proporciona la ubicación base de la imagen
* @param nombrar la ubicación de la imagen, en relación con el argumento url
* @devolver la imagen en la URL especificada
* @ver Imagen
*/
público Imagen obtener la imagen(URL URL, nombre de cadena){
probar {
devolver obtener la imagen(nuevo URL(url, nombre));
 } captura (MalformedURLException e) {
devolvernulo;
 }
}

Cuando Javadoc procesa el código anterior, genera una página web similar a la siguiente:

Un navegador muestra la salida de Javadoc de la misma manera que muestra cualquier documento HTML. Javadoc ignora los espacios en blanco y los saltos de línea adicionales a menos que use etiquetas HTML para crear ese espacio.

Las @tags utilizadas al final del comentario generan el Parámetros, Devoluciones, y Ver también secciones que ves.

Debes seguir el @param etiqueta con el nombre del parámetro, un espacio y una descripción del mismo. En el caso anterior, hay dos parámetros: URL y nombre. Observe que ambos aparecen bajo el mismo encabezado Parámetros en la salida de la documentación. Puede enumerar tantos parámetros como sean necesarios para la función o el método que está describiendo.

los @devolver etiqueta documenta el valor que devuelve la función, si es que lo hace. Puede ser una simple descripción de una palabra o muchas oraciones, según las circunstancias.

los @ver tag le permite etiquetar otras funciones relacionadas o relevantes. En este caso, la etiqueta @see se refiere a otra función llamada simplemente Imagen. Tenga en cuenta que las referencias hechas con esta etiqueta son enlaces en los que se puede hacer clic, lo que permite al lector saltar al elemento al que se hace referencia en el HTML final.

Hay más etiquetas disponibles, como @version, @author, @exception y otras. Cuando se usan correctamente, las etiquetas ayudan a relacionar los elementos entre sí y permiten navegar fácilmente por la documentación.

Ejecutar Javadoc en su código fuente

Invoca Javadoc en la línea de comandos. Puede ejecutarlo en archivos individuales, directorios completos, paquetes Java o en una lista de archivos individuales. De forma predeterminada, Javadoc generará los archivos de documentación HTML en el directorio donde ingresa el comando. Para obtener ayuda sobre los comandos específicos disponibles, simplemente ingrese:

javadoc --ayuda

Para ver exactamente lo que Javadoc puede hacer con más detalle, consulte la documentación oficial de Oráculo. Para crear un conjunto rápido de documentación en un solo archivo o directorio, puede ingresar javadoc en la línea de comando seguido de un nombre de archivo o comodín.

javadoc ~/code/nombre de archivo.java
javadoc ~/code/*.Java

Arriba hay una lista de los archivos y directorios que ha creado Javadoc. Como puede ver, hay bastantes de ellos. Por esta razón, debe asegurarse de no estar en el mismo directorio que su código fuente cuando ejecuta el programa. Si lo hace, podría crear un gran lío.

Para ver sus documentos recién creados, simplemente abra el índice.html archivo en su navegador preferido. Obtendrá una página como la siguiente:

Esta es la documentación para una sola clase de Java breve para demostrar el resultado. El encabezado muestra el nombre de la clase, así como los métodos incluidos en ella. Desplazarse hacia abajo revela definiciones más detalladas de cada uno de los métodos de clase.

Como puede ver, para cualquier tipo de proyecto Java, especialmente los grandes con miles de líneas de código, este tipo de documentación es invaluable. Sería un desafío aprender sobre una gran base de código leyendo su código fuente. Las páginas de Javadoc hacen que este proceso sea mucho más rápido y fácil de seguir.

Javadoc puede ayudarlo a mantener su código Java y toda la documentación relevante organizada y fácil de usar. Ya sea que lo estés haciendo por tu propio futuro olvidadizo o para facilitar las cosas para un equipo grande, Javadoc es una herramienta poderosa que puede cambiar la forma en que escribe e interactúa con su codificación Java proyectos

Los 8 mejores blogs de Java para programadores

Leer siguiente