[Programación] Re: [LUG.ro] Proyecto suscripción a jornada s

[Nicolás Aimetti]

Doxigen, el tema pendiente...
Lo que hace básicamente doxygen es generar documentación acerca de un 
proyecto en particular
a partir de los datos obtenidos al parsear las fuentes del mismo. Lo 
cual implica que así
nosotros no hayamos documentado aun nada de un proyecto doxygen puede 
decirnos bastantes cosas acerca del mismo, como por ejemplo que 
funciones se encuentran definidas en tal proyecto, en que archivos 
están, sus prototipos, que clases hay definidas, que atributos poseen, 
que métodos públicos, que métodos privados, etc...

El tema es ir luego uno nutriendo toda está información con datos extras 
como por ejemplo para que sirve tal función, que valor devuelve, que 
guarda tal variable y demás...

¿Como se logra esto? Mediante comentarios en el código que doxygen es 
capaz de interpretar. (tb se pueden especificar en un archivo separado, 
es bastante flexible).

Doxygen procesa todo comentario que empiece de la forma
/**
 Comentario
*/
o bien

/*! Comentario
*/

o bien

///
/// ... text ...
///

y otras cuantas formas más: 
http://www.stack.nl/~dimitri/doxygen/docblocks.html

Uno puede documentar una función de la siguiente manera:

/**
  Reemplaza la extension del del archivo $file por $sfx
 */

function cambiar_sufijo($file,$sfx) {
        etc...

O mejor aun...

/*!
  Reemplaza la extencion del del archivo $file por $sfx
  \param $file nombre del archivo
  \param $sfx  Sufijo (sin el punto).
  \return  0 en caso de exito, != 0 en caso contrario.
*/

function cambiar_sufijo($file,$sfx) {
        etc...

Doxigen entiende ciertos comandos dentro de los comentario que parsea, 
como por ejemplo
\param el cual le especifica que el siguiente comentario se aplica a un 
parametro de la funcion,
\return que se aplica al valor que devuelva la función...
La lista de estos comando es larga:
http://www.stack.nl/~dimitri/doxygen/commands.html
además se pueden especificar comandos html:
http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
y hacer un montón de cosas más...

Espero que vayan entendiendo la idea básica... un ejemplo de como queda 
una clase documentada
usando doxygen: http://xml.apache.org/xerces-c/apiDocs/classDOMBuilder.html

Bueno... doxygen puede correrse desde la linea de comando al igual que 
uno corre el gcc o cualquier otro programa, el mismo lee un archivo de 
configuración el cual les especifica que archivos corresponden al 
proyecto, que formato de documentación generar, etc...

Gracias a dios también existe una interfaz gráfica: doxywizard que 
simplifica bastante la cosa...
Los ejemplos que dí aquí son bastantes escuetos, pero en la pagina: 
http://www.stack.nl/~dimitri/doxygen/index.html y más precisamente en el 
manual: http://www.stack.nl/~dimitri/doxygen/manual.html sobran los 
ejemplos...

y para los más cholulos aquí hay una lista con los proyectos que lo 
utilizan:
http://www.stack.nl/~dimitri/doxygen/projects.html

Bueno, espero que les interese.

Saludos,
       Nicolás.