Juan va a utilizar JavaDoc para documentar las clases que ha desarrollado. Ana se da cuenta de la ayuda tan importante que ofrece, tanto para el futuro mantenimiento de la aplicación como para entender su funcionamiento, tener documentadas las clases.
Existen diferentes herramientas que permiten automatizar, completar y enriquecer nuestra documentación. Podemos citar JavaDoc, SchemeSpy y Doxygen, que producen una documentación actualizada, precisa y utilizable en línea, incluyendo además, con SchemeSpy y Doxygen, modelos de bases de datos gráficos y diagramas.
Las clases que se implementan en un aplicación, deben de incluir comentarios. Al utilizar un entorno de programación para la implementación de la clase, debemos seguir una serie de pautas, muchas de las cuales las realiza el IDE de forma trasparente, en el diseño y documentación del código.
Los entornos de programación que implementa Java, como Eclipse o Netbeanss, incluyen una herramienta que va a generar páginas HTML de documentación a partir de los comentarios incluidos en el código fuente. La herramienta ya se ha indicado en los puntos anteriores, y es JavaDoc.
Para que JavaDoc pueda generar las páginas HTML es necesario seguir una serie de normas de documentación en el código fuente, estas son:
Con el uso de los entornos de desarrollo, las etiquetas se añaden de forma automática, estableciendo el @author y la @version de la clase de forma transparente al programador-programadora. También se suele añadir la etiqueta @see, que se utiliza para referenciar a otras clases y métodos.
Dentro de la la clase, también se documentan los constructores y los métodos.
Existe una serie de etiquetas que fijan como se presentará la información en la documentación resultante JavaDoc. En la url https://en.wikipedia.org/wiki/Javadoc aparece una colección de palabras reservadas (etiquetas) definidas en Javadoc. A continuación se muestran algunas de las más utilizadas.
|
Etiqueta y parámetros |
Uso |
Asociada a |
|---|---|---|
|
@author nombre |
Nombre del autor (programador) |
Clase, interfaz |
|
@version numero-version |
Comentario con datos indicativos del número de versión. |
Clase, interfaz |
|
@since numero-version |
Fecha desde la que está presente la clase. |
Clase, interfaz, campo, método. |
|
@see referencia |
Permite crear una referencia a la documentación de otra clase o método. |
Clase, interfaz, campo, método. |
|
@param seguido del nombre del parámetro |
Describe un parámetro de un método. |
Método. |
|
@return descripción |
Describe el valor devuelto de un método. |
Método. |
|
@exception clase descripción |
Comentario sobre las excepciones que lanza. |
Método. |
|
@deprecated descripción |
Describe un método obsoleto. |
Clase, interfaz, campo, método. |
Los campos de una clase, también pueden incluir comentarios, aunque no existen etiquetas obligatorias en JavaDoc.
Lenguaje de Marcado de Hipertexto, es el lenguaje utilizado en la elaboración de las páginas web.
Es un metadato que ayuda a describir un item.
Para documentar el código, el equipo de desarrollo de BK Programación, ha decidido utilizar JavaDoc, por lo que todos los componentes del equipo de desarrollo, debe familiarizarse con la herramienta.