Doxygen : documentar tu codigo muy rapido

La semana anterior hablábamos sobre Zeal, el programa con el que conseguir la documentación necesaria para programar. Siguiendo en esa línea, hoy os vengo a hablar de Doxygen, un programa con el que documentar tu código muy rápido.

Doxygen

Doxygen es el programa que nos va a permitir generar una documentación completa y profesional de cualquiera de nuestros proyectos y en cualquier de los lenguajes que utilicemos. Da igual que seamos más de Java, que de C que de PHP. Todos los proyectos que queramos distribuir o guardar para uso personal, deben estar bien documentados.

Documentar, ese proceso pesado y odiado

Seamos realistas, a nadie nos gusta documentar nuestro código y mucho menos generar esos grandes manuales de varias decenas de hojas donde explicamos cada una de las funciones y cómo funciona nuestro código. Por estas cosas, muchos proyectos personales se quedan sin documentar e incluso algunos proyectos comunitarios carecen de una buena.

La cosa cambiaría si hubiera una manera simple, rápida y poco costosa de realizar todo este proyecto.

Escribiendo el código para Doxygen

Para que Doxygen pueda generar la documentación es necesario, escribir algunos comandos dentro de nuestro código, para que él lo entienda.

Este es un pequeño código de ejemplo, de una parte de un programa mío.

/**
* @file queue.c
* @Author ganchito55
* @date 28/9/2014
* @brief Queue implementation
*/

#include 
#include 
#include 
#include "queue.h"

/**
* @brief Create a Queue
* @param Queue pointer
* @return 0 if all run ok, -1 for no enough memory
*/
int createQ(Queue *q){
Node *n;
    if((n=malloc(sizeof(Node)))==NULL){
        fprintf(stderr,"Error: no enough memory");      
        return -1;
    }
    n->next=NULL;
    strcpy(n->info,"FRONT");
    q->back=n;
    q->front=n;
    return 0;
}
/**
* @brief Is a Queue empty 
* @param Queue pointer
* @return 0 if empty, -1 no empty 
*/
int emptyQ(Queue *q){
    if(q->front==q->back){
        return 0;
    }
    else{
        return -1;
    }
}

Si sois observadores veréis que hay una sintaxis muy concreta en los comentarios. Esta sintaxis es la que utilizará Doxygen.

Generando la documentacion con Doxygen

Utilizando simplemente este código y la interfaz de nuestro generador de documentacion vamos a obtener con muy pocos pasos, una documentación completa.

Lo primero que vamos a hacer es configurar nuestro proyecto:

Luego configuramos el lenguaje que hemos utilizado:

Después el formato de nuestra documentación:

Luego seleccionamos si queremos que nos realice unos diagramas:

Finalmente tenemos la documentación:

Si estáis interesados en este enlace esta toda la información, los enlaces de descarga tanto para Windows, como para Mac y Linux y la manera de usarlo.

Espero que esta entrada os haya gustado y si tenéis cualquier comentario o duda, intentaremos responderlo.