Esta es una de las tareas que nos permiten recordar como realizamos un desarrollo de una aplicación o parte de un proyecto y permite obtener un apoyo importante cuando se requieren cambios y hemos pasado muchos meses o hasta años sin volver a tener contacto con un proyecto o una parte del código fuente, es por ello la relevancia de esta fase y lo olvidado que se encuentra en muchos desarrolladores.

Los objetivos más destacables de la documentación de un proyecto de software son:

1. Informar sobre la función de los diferentes componentes.
2. Indicar su funcionamiento interno, si hay algo descatable.
3. Facilitar la depuración.
4. Permitir la revisión.
5. Hacer el proyecto apto para ser desarrollado por varias personas.
6. Facilitar un manteniemto futuro.
7. Controlar cambios, para conocer la evolución del proyecto: el estdo actual y lo que falta hasta el siguiente hito.
8. Servir como recordatorio al programador y una guia de referencia.
9. Evitar tener que descifrar el funcionamiento del código ofreciendo una visión al más alto nivel posible.
10. Reflejar advertencias, personal de contacto, contribuidores, aspectos de licenciamiento, etc.

La documentación de un proyecto por lo general no persigue enseñar a alguien a hacer un programa o trozo de código. Tampoco pretende reflejar obviedades relativas al código o a su organización.

Veremos una herramienta que ayuda en la documentación de programas. La cual es capaz de generar archivos de ayuda a partir de los comentarios que se hayan escrito junto con el código del programa(s). Esta manera de generar la documentación del código tiene la ventaja de evitar tener que escribirla por duplicado una vez como un comentario dentro del programa y la otra como la documentación externa.

Se ha definido para la documentación del código el uso de la herramienta Doxygen, debido a su gran auge y su uso masivo en open-source. Esta herramienta es capaz de generar archivos en hipertexto en varios formatos a partir de la estructura interna de nuestros programas y de los comentarios que contengan.

Dependiendo de la distribución que estemos usando, habrán diferentes modos de instalar esta herramienta, pero a modo de ejemplo usaremos un clásico, mostraremos la forma de instalarla en Debian Etch.

    #apt-get install doxygen doxygen-doc doxygen-gui

Con este simple comando, ya tenemos disponible nuestra poderosa herramienta de documentación.

Como ya tenemos instalado nuestra herramienta, se debe como primera medida generar un archivo de configuración con el nombre de nuestro programa o proyecto. Este archivo reflejará las opciones que deberán ser tenidas en cuenta, cuando se genere la documentación.

Para generar este archivo de configuración deberemos ejecutar el comando siguente:

    $ doxygen -g myfile.doxy

Con esto hemos generado en el proyecto o programa, un archivo denominado myfile.doxy, el cual contiene todos los comandos que seran interpretado por doxygen para generar los archivos de documentación. La extensión del archivo debe ser siempre doxy, sólo para guiarnos, ya que lo que importa es su contenido, el cual será interpretado por doxygen.

El archivo generado contiene una infinidad de opciones del programa, pero nos centraremos en las más comunes o las más usadas.

  PROJECT_NAME          = "Prueba de la clase rational" // Nombre delproyecto entre comillas dobles
  PROJECT_NUMBER        = 0.1                           // Versión del código fuente del programa
  OUTPUT_LANGUAGE       = Spanish                       // Lenguaje en que se generará
  OUTPUT_DIRECTORY      = ./doc/.                       // Directorio en donde quedará la documentación
  GENERATE_LATEX        = NO
  GENERATE_MAN          = NO
  GENERATE_RTF          = NO
  CASE_SENSE_NAMES      = YES
  INPUT                 = rational.h rational.cpp rat-calc.cpp rat-tst.cpp ADH_port.h  //Archivos fuente que componen el proyecto
  RECURSIVE             = NO
  QUIET                 = YES
  JAVADOC_AUTOBRIEF     = YES
  EXTRACT_ALL           = YES                           //Documenta un programa que no tiene los estilos de comentario de doxygen Si/No?
  EXTRACT_PRIVATE       = YES
  EXTRACT_STATIC        = YES
  EXTRACT_LOCAL_CLASSES = YES
  INLINE_INHERITED_MEMB = YES
  SOURCE_BROWSER        = YES                           //Se genera una documentación que hace referencia (hiperenlace) a una copia del código fuente Si/No?
  INLINE_SOURCES        = NO
  STRIP_CODE_COMMENTS   = NO
  REFERENCED_BY_RELATION= NO
  REFERENCES_RELATION   = NO
  FULL_PATH_NAMES       = NO
   
  SORT_MEMBER_DOCS      = NO
  SORT_BRIEF_DOCS       = NO
  CLASS_DIAGRAMS        = YES
  
  ENABLE_PREPROCESSING  = YES
  MACRO_EXPANSION       = YES
  EXPAND_ONLY_PREDEF    = YES
  PREDEFINED            = "DOXYGEN_COMMENT" "_MSC_VER=1300"
  
  #--- TODOS ESTOS SON MENOS COMUNES ---
  # DISTRIBUTE_GROUP_DOC = YES
  # ENABLE_PREPROCESSING = YES
  # EXAMPLE_PATH         = example_test.cpp
  # FILE_PATTERNS        = diagrams_*.h
  # GENERATE_TAGFILE     = example.tag
  # HAVE_DOT             = YES
  # PERL_PATH            = perl
  # TAGFILES             = example.tag=../../example/html

Claramente el contenido de este archivo de configuración tiene muchas mas opciones, pero hemos tratado de rescatar las opciones más usadas.

Hay muchos detalles en el formato también, aca describiremos los principales y agregaremos en la medida que vayamos aprendiendo.

• Nombre del archivo fuente

Para indicar a doxygen el nombre del archivo fuente se debe usar la sentancia @file nombre_del_archivo.c

Comentarios Parten siempre con slash + asterisco + asterisco y terminan con un asterisco + slash

Primera linea en el Comentario Esta primera linea es sólo un resumen de una linea.

Argumentos Los argumentos de la función se utiliza la sentencia @param.

Valor devuelto por una función El valor devuelto por una función de indica mediante sentencia @return.

Enlace a otras funciones Para realizar enlaces a otras funciones se relaiza con la sentencia siguiente @see.

Comentarios en una linea en el Código Para realizar un comentario sobre una linea en el código se hace de la siguiente forma, /**< Comentario en una linea sobre el código */ y de esta otra forma /< Otro comentario en una sola linea en el código Otras opciones que son significativas son: