Introducción a Doxygen

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

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.

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
/* lineas comentadas */	/ Tag para doxigen */
comentario de linea	/ comentario de linea para doxigen

comentario normal bash	TAG para ser procesado por doxygen en bash
# comentario de bloque # comentario de bloque	#/ # Tag 1 para doxigen # Tag 2 para doxigen #*/
# 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)

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

Observaciones de la imagen: