[[PageOutline]]

= Introducción a Doxygen =
Doxygen es un documentador automático, capaz de extraer la documentación de los propios fuentes del programa. [[BR]]
Debemos de documentar manualmente algunos tags como nombre de la función, breve descripcion, parametros, notas, autor.... [[BR]]
Doxigen de manera automáticamente genera las referencias de una función, o desde donde es referenciada.  [[BR]]

En la imagen podemos ver como se puede navegar por las librerias, aunque también se puede navegar por orden alfabético de las funciones.

[[Image(example.salida.png, 90%)]]
 

= Instalación Doxygen =
Apt-get install doxygen doxygen-doc doxygen-gui graphviz

= Comentar el código para incluir tags doxygen =
Los tags de doxygen deben estar dentro de lineas comentadas en el código, 

|| comentario normal C  || TAG para ser procesado por doxygen en C ||
|| /* [[BR]] lineas comentadas [[BR]]  */      || /** [[BR]] Tag para doxigen  [[BR]] */ ||   
|| //  comentario de linea   ||  /// comentario de linea para doxigen ||

[[BR]]

|| comentario normal bash || TAG para ser procesado por doxygen en bash ||
|| # comentario de bloque [[BR]] # comentario de bloque      || #/** [[BR]] # Tag 1 para doxigen  [[BR]] # Tag 2 para doxigen  [[BR]] #*/ ||   
|| # comentario de linea   || # /// tag para doxigen ||

== Modificaciones especiales para el lenguaje bash cuan usamos el /* ==
Doxygen está preparado para documentar C, y no bash. 

En muchas ocasiones utilizamos en bash, /* para muchas operaciones, pero doxygen lo va a interpretar como comentario del fuente y si no encuentra un */ (fin comentario) tendremos errores. 

Cuando estemos programando y tenemos la intención de autodocumentar con Doxygen, debemos de tener en cuenta:
Si utizamos los caracteres que se utilizan para comentar en C ( /* ) debemos de colocar despues # */   Requisito para Doxygen.

Por ejemplo 
{{{
# este comentario de bash es para indicar que en la linea siguiente, debemos de colocar dentro de un comentario bash el fin de comentario C, 
# ya que la instrucción cp utiliza los caracteres que usa C para iniciar comentarios.
cp origen/* /destino   # */ Requisito para Doxygen 
}}}

otro ejemplo, uso del /* en código bash más complejo:
{{{
# nota: en la siguiente linea doxygen encuentra comentario /* así que debemos insertar # */ . Pero además debemos cerrar corchetes, comas ....
 FILEPATH="${FILEPATH}/$(ls -A | grep -i -m1 "^${FILE%%/*}$")" || return $?   # */}$")" (necesario Doxygen)
}}}

[[br]]
Las funciones bash deben estar OBLIGATORIAMENTE en el siguiente formato:
{{{
function ogBoot () 
{
  codigo
}
}}}

En caso contrarió no generará bien las dependencias.

== Plantilla para documentar funciones ==

Se ha acordado utilizar la siguiente plantilla para documentar con Doxygen las funciones BASH del motor de clonación.

{{{
#/**
#         nombreFunción tipo_param ...                (formato de la función).
#@brief   Descripción breve de la función.
#@param   tipo_param   Descripción del parámetro      (una línea por cada parámetro).
#@return  tipo_valor - Valor devuelto por la función.
#@exception TipoError  Descripción del error          (1 línea por cada error).
#@note    Nota sobre la función                       (opcional).
#@warning Aviso importante sobre la función           (opcional).
#@todo    Trabajo pendiente de realizar               (opcional).
#@version versión - Descripción de la versión o los cambios.
#@author  Autor, Universidad                         (1 línea por cada autor).
#@date    Fecha                                      (año-mes-día)
#*/ ##
function nombreFunción ()
{
# Comentario normal del código.
...
#/// Comentario especial para incluir en la documentación Doxygen.
...
}
}}}

Debe documentarse un histórico completo de cambios de cada función, incluyendo tantas tripletas de etiquetas {{{@version}}}, {{{@author}}} y {{{@date}}} como sean necesarias.

La línea final del comentario general ({{{#*/ ##}}}) es necesaria para que Doxygen reconozca las dependencias de la función, puesto que la sintaxis de BASH se asemeja más a la de Python que a la de C/C++.


= Generar la Documentación =

Ejecutar el script {{{trunk/install/ogGenerateDoc.sh}}} con el siguiente formato:
 * Parámetro 1:     {{{str_pathFuentes}}}
 * Parámetro 2:     {{{str_pathdestino}}}

Ejemplos de ejecución:
{{{
ogGenerateDoc.sh trunk/client/engine/ /opt/opengnsys/doc/engine
ogGenerateDoc.sh trunk/administrator/web/ /opt/opengnsys/doc/administrator_web
}}}


= Ejemplos =
== Ejemplo de documentación ==
{{{
function ejemplo () 
{
#/**  @function FunExample: @brief ejemplo de codigo bash para doxygen
#@param $1 str_pathOrgien
#@param $2 str_pathDestino
#@param ejemplo FunExample /var/EAC/admin/librerias /var/EAC/documentcion/
#@return genera la documentacion en el path indicado como parametro 2.
#@warning  Salidas de errores no determinada
#@attention
#@version 1.0       Date: 01/06/2009                 Author 
#@note	  Notas sin especificar
#*/
echo "La línea siguientes es un comentario solo para bash"
# comentario solo para bash
echo "La linea siguiente es un comentario tanto para bash como para doxygen"
# /// FIXME: falta controlar los errores
echo "Ojo si se inserta un /*, , debemos terminar la instruccion con " # */
cp /pruebas/*  /destino   # */
echo "Para insertar un comentario para que también lo interprete doxygen"
# /// FIXME: falta controlar los errores
}
}}}

== Ejemplo de salida documentación ==
[[Image(example.salida.png, 90%)]]
Observaciones de la imagen: