¶ 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 |
<a id"/**"> # Tag 1 para doxigen # Tag 2 para doxigen <a id"*/"> |
| # 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)
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 (#*/ <a id"#)"> 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: