as2Api. Documentando proyectos 2
Puestos a documentar, documentemos todo, incluidas las clases de ActionScript 2.
Al trabajar y crear clases, intuitivamente voy documentando las mismas en estilo JavaDoc. Ahora bien, cuando el número de paquetes, clases e interfaces, es numeroso, interesa tener toda esta documentación a mano. Interesa generar toda esa documentación que está en formato comentario, como HTML.
Y a partir de esta necesidad, surge el estudio de varias herramientas de generación
Antes de nada, indicar que no se ha tratado de un estudio exhaustivo, sino de una búsqueda más o menos rápida de una herramienta que sirva. Las herramientas estudiadas han sido:
- VisDoc. Herramienta de pago, con un precio considerable. Eso sí, genera documentación en multitud de formatos, formas y colores. Puedes modifiar apariencia mediante CSS, etc... La versión trial, te trastoca alguna clase. Es justo decir que probablemente las mejores documentaciones que he visto, están hechas con VisDoc. De ahí su precio. Herramienta para mac.
- ZenDoc. Herramienta gratuita. Como problema plantea la necesidad de un servidor ( realizada con php ) y de subir las clases a cierto directorio del mismo ( en función de donde instalemos la aplicación ).
- Natural Docs. Probablemente la más conocida. Con soporte para numerosos lenguajes. El principal problema radica, en la forma de documentar el código, diferente al modo habitual de JavaDocs. Por lo que habría que re-escribir los comentarios. Seguramente exista una herramienta, que lo haga, y es posible incluso que NaturalDocs también pueda interpretar los comentarios JavaDoc ( llamémosles así ). Pero en el momento de realizar la búsqueda de la herramienta, apremiaba la urgencia
- Jellyvision actiondoc. En beta. Tiene buena pinta, y es fácil de usar. Se arrastran las clases al interface, y se pulsa el botón de generar. El problema, que no mantiene la estructura de paquetes ( al menos en una primera prueba rápida )
- as2Doc De pago. Con una versión trial que a diferencia de VisDoc, no trastoca nada. La versión de pago, ofrece prestaciones interesantes, generación en xml, xhtml, etc... pero al menos la trial, a no ser que tenga alguna opción escondida que no ví, plantea el mismo problema que la herramienta anterior con la estructura de paquetes
- as2Api Genera la documentación con el formato "estándar" de los javadocs. Con los frames, la estrucutra de paquetes, etc.. Funciona en windows, linux y mac, con Ruby ( el ejecutable de windows trae Ruby ). Una línea de comando y genera la documentación desde el directorio indicado al directorio de destino indicado. Una única pega. Desde la versión 0.3, los métodos privados son excluidos de la documentación generada. Sí, esto es lógico, dado que un javaDoc habitualmente es para proporcionar una API pública. Ahora bien, cuando se trata de documentar internamente, preferiría poder tener toda la clase documentada. A diferencia de otras de las aplicaciones nombradas anteriormente que sí tenían la opción de decidir sobre este tema, esta herramienta no la tiene. Quizás y para compensar, existe la posibilidad de generar junto al javadoc de cada clase, un archivo HTML con el código completo de la misma, enlazado desde el javadoc. De ese modo, se pueden visualizar todos los métodos de la clase.
Pese a esta "limitación" ( entrecomillado porque en realidad no es tal ), ha sido la herramienta escogida por su rapidez, comodidad de uso y resultados obtenidos.