Documentando clases bajo Action Script con NaturalDocs

A raíz del lanzamiento de la sección de proyectos opensource de BlocketPC, estuvimos consultando sistemas de documentación automatizada para las clases que empleábamos en dichos proyectos. Mirando y mirando, encontramos alguna solución interesante (en mi caso no me servía al ser para mac), y finalmente dimos con NaturalDocs (existen otras conocidas como ZenDoc y As2Doc). De regalito, os dejamos una comparativa de algunas de ellas en osflash.

Si bien es algo curioso volver a la ventana de comandos para hacer nuestros pinitos, tenemos que decir que funciona y muy bien! Además poniendo un poco de atención a su documentación, podemos agradecer que los comentarios tipo JavaDoc que nos insertan plugins como FDT para eclipse, están bastante soportados.

El resultado lo podéis ver aquí y aquí.

Un ejemplo de como trabajar con NaturalDocs.
Imaginamos que tenemos nuestras clases en una carpeta llamada proyecto/src/classes/ y queremos generar la documentación en proyecto/doc/. La cosa sería tal que así:

NaturalDocs -i C:proyectosrcclasses
-o FramedHTML C:proyectodoc
-p C:proyectodocnatural

Donde el primer parámetro es el directorio donde se encuentran las clases de las que se generará la documentación (se puede hilar más fino), el segundo es por un lado si la documentación se va a generar con un frame, o HTML sin frames (formato de salida), además de la carpeta donde se va a generar, y el tercero es el directorio donde NaturalDocs guardará los archivos que emplea para llevar un control sobre la generación de documentación. Debe ser exclusivo para cada proyecto.

Una de las grandes e interesantes características de NaturalDocs es que cada vez que generas la documentación, comprueba lo que ha cambiado de la anterior, y solamente actualiza las partes necesarias. Otra cosa que es muy agradable, es lo sencillo que es cambiar los CSS de la documentación generada en HTML, para personalizarla.

En general no se documentan las clases, y si de la que se programan, se tiene un poco de cuidado comentando los métodos y los parámetros, no resulta tan costoso. Y luego generar una documentación aceptable es tan sencillo como esto. No os voy a decir que para un banner documentéis, pero si váis a hacer un proyecto curioso o en el que trabaje más gente, o desde luego si lo váis a hacer público, os animo a hacerlo!