Doxygen : documentar tu codigo muy rapido

por:

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 para generar la documentacion de una manera sencilla y rapida.

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:

Configurando Doxygen

Luego configuramos el lenguaje que hemos utilizado:

Configurando DoxygenDespués el formato de nuestra documentación:

Configurando Doxygen

Luego seleccionamos si queremos que nos realice unos diagramas:

Configurando DoxygenFinalmente tenemos la documentación:

Documentacion generada por Doxygen

 

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.

 

3 comentarios en “Doxygen : documentar tu codigo muy rapido”

  1. Mati

    En que momento seleccionas el archivo? saludos.

    Responder
    • Mat

      y que formato tiene que ser?

      Responder
      • SomosBinarios

        La documentación no se genera indicando archivo por archivo, sino que se indica la ruta donde están todos los ficheros con el código:

        Los ficheros de código estarán en su formato usual, .c si usas C, .php si usas PHP, .cs si usas C# etc.

        Responder

Deja una Respuesta