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

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 

Las funciones bash deben estar OBLIGATORIAMENTE en el siguiente formato:

function ogBoot () 
{
  codigo
}

En caso contrarió no generará bien las dependencias.

tag de doxygen

Generar la Documentación

trunk/install/ogGenerateDoc.sh Parametro 1 $str_pathFuentes Parametro 2 $str_pathdestino.

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 Antonio J. Doblas Viso. Universidad de Malaga
#@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: