De igual forma que en BK programación se ha decidido someter a estudio la aplicación phpDocumentor para así poder decidir su implantación, lo mismo ha ocurrido con JavaDoc. De esta manera se está investigando el funcionamiento, configuración, limitaciones, etc. de JavaDoc, que nos permitirá desarrollar documentación de forma automatizada de los programas Java que en la empresa se desarrollen.
Se pueden encontrar en la red diversas reglas para la generación de documentación de los programas en Java, cada una de ellas con unas características específicas, aunque todas persiguen el mismo objetivo que es documentar los programas Java para que sean más legibles.
Javadoc es una utilidad de Sun Microsystems empleado para generar APIs (Aplication Programing Interface) en formato HTML de un archivo de código fuente Java. Javadoc es el estándar de la industria para documentar clases de Java, la mayoría de los IDEs los generan automáticamente. Esto facilita la tarea de los desarrolladores, ya que, con sólo seguir una serie de reglas a la hora de generar los comentarios en su código, podrán obtener una buena documentación simplemente usando esta herramienta.
La finalidad de Javadoc es intentar evitar que la documentación se quede rápidamente obsoleta cuando el programa continúa su desarrollo y no se dispone del tiempo suficiente para mantener la documentación al día. Para ello, se pide a los programadores de Java que escriban la documentación básica (clases, métodos, etc.) en el propio código fuente (en comentarios en el propio código), con la esperanza de que esos comentarios sí se mantengan actualizados cuando se cambie el código. La herramienta Javadoc extrae dichos comentarios y genera con ellos un juego de documentación en formato HTML.
Básicamente Javadoc es un programa, que recoge los comentarios que se colocan en el código con marcas especiales y construye un archivo HTML con clases, métodos y la documentación que corresponde. Este HTML tiene el formato de toda la documentación estándar de Java provista por Sun.
La documentación a ser utilizada por Javadoc se escribe en comentarios que comienzan con /** y que terminan con */ , comenzando cada línea del comentario por * a su vez, dentro de estos comentarios se puede escribir código HTML y operadores para que interprete Javadoc (generalmente precedidos por @) .
Javadoc localiza las etiquetas incrustadas en los comentarios de un código Java. Estas etiquetas permiten generar una API completa a partir del código fuente con los comentarios. Las etiquetas comienzan con el símbolo @ y son sensibles a mayúsculas-minúsculas. Una etiqueta se sitúa siempre al principio de una línea, o sólo precedida por espacio(s) y asterisco(s) para que la herramienta Javadoc la interprete como tal. Si no se hace así las interpretará como texto normal.
Hay dos tipos de etiquetas:
@etiqueta{@tag}, es decir, se escriben entre los símbolos de llaves./** y que terminan con */ @ y son sensibles a mayúsculas-minúsculas.