LA DOCUMENTACIÓN AUTOMATIZADA

2- LA DOCUMENTACIÓN AUTOMATIZADA:

En muchas ocasiones se pide un manual de referencia del código. Esto es especialmente importante a la hora de crear una librería que esté ideada para que otro programador la use en una aplicación final. Este manual engloba de alguna forma un trabajo doble: hay que explicar bien el funcionamiento de cada función en el código mismo y luego repetir la misma información en un documento de texto.

De este trabajo pueden encargarse sistemas de documentación automáticos. Leen el código y extraen la información necesaria para generar la documentación. Muchas veces permiten varios tipos de documentos de salida: en formato HTML, en formato PDF, como fichero de HTML comprimida (CHM) o en formato “Rich Text”.

Probablemente el más influyente de estos sistemas es javadoc. Fue incluido en el entorno Java de Sun como una parte integral del sistema y ha marcado desde entonces el formato de los comentarios de documentación. El programa de más uso es probablemente doxygen, ya que puede entender la sintaxis de muchos lenguajes, muy especialmente de C++. Para PHP es recomendable usar php documentos.

A todos estos sistemas es común que requieren un marcador especial para los comentarios que se exportan del código a la documentación final. El más extendido es el de javadoc que marca los comentarios entre  Nota que es nada más que un comentario al estilo donde la primera letra es un asterisco. Sin embargo, para el sistema de documentación, el segundo asterisco en la marca como un comentario de documentación cuyo contenido será procesado por el sistema de documentación automatizado.