11.4.2. Generación de documentación a partir del código fuente.
Conocemos los comentarios de bloque (/* hasta */) y los comentarios hasta final de línea (a partir de una doble barra // ).
Pero en algunos lenguajes modernos, como Java y C#, existe una posibilidad adicional que puede resultar muy útil: usar comentarios que nos ayuden a crear de forma automática cierta documentación del programa.
Esta documentación típicamente será una serie páginas HTML enlazadas, o bien varios ficheros XML.
Por ejemplo, la herramienta (gratuita) Doxygen genera páginas como ésta a partir de un fuente en C#:
La forma de conseguirlo es empleando otros dos tipos de comentarios: comentarios de documentación en bloque (desde /** hasta */) y los comentarios de documentación hasta final de línea (a partir de una triple barra /// ).
Lo habitual es que estos tipos de comentarios se utilicen al principio de cada clase y de cada método, así:
/** * Personaje: uno de los tipos de elementos graficos del juego * * @see ElemGrafico Juego * @author 1-DAI 2008/09 */ public class Personaje : ElemGrafico { // Mueve el personaje a la derecha, si es posible (sin obstáculos) public void MoverDerecha() { (...) } (...) /// Animación cuando el personaje muere: ambulancia, etc. public void Morir(){ (...) } }
Además, es habitual que tengamos a nuestra disposición ciertas "palabras reservadas" para poder afinar la documentación, como @returns, que da información sobre el valor que devuelve una función, o como @see, para detallar qué otras clases de nuestro programa están relacionadas con la actual.
Así, comparando el fuente anterior y la documentación que se genera a partir de él, podemos ver que:
- El comentario de documentación inicial, creado antes del comienzo de la clase, aparece en el apartado "Descripción detallada".
- El comentario de documentación del método "Morir" se toma como descripción de dicha función miembro.
- La función "MoverDerecha" también tiene un comentario que la precede, pero está con el formato de un comentario "normal" (doble barra), por lo que no se tiene en cuenta al generar la documentación.
- "@author" se usa para el apartado "Autor" de la documentación.
- "@see" se emplea en el apartado "Ver también", que incluye enlaces a la documentación de otros ficheros relacionados.
En el lenguaje Java, documentación como esta se puede crear con la herramienta JavaDoc, que es parte de la distribución "oficial" del lenguaje. En cambio, en C#, la herramienta estándar genera documentación en formato XML, que puede resultar menos legible, pero se pueden emplear alternativas gratuitas como Doxygen.