Comenzando con Doxygen

Doxygen logoDoxygen es un generador de documentación que extrae la información de los archivos fuente.

Soporta varios lenguajes de programación como son C, C++, Java, PHP, Python, IDL, Fortran, VHDL, Tcl, y un poco de D.

El formato más popular para generar documentación es HTML, pero también genera en los formatos Latex, RTF, PostScript, PDF y Paginas Man.

Un ejemplo del formato y diseño de la documentación generada en formato HTML se puede ver en la página oficial del programa: doxygen.org, ya que la misma es construida a través de Doxygen.

¿Como documentar para Doxygen

Documentar para Doxygen es tan fácil como poner comentarios dentro del código fuente antes de cada declaración de clase, método, objeto o variable que se quiera.

En los archivos C es preferible que la documentación se ponga en los archivos de cabecera .h y no en la implementación del código que se hace en los archivos .c

En lenguajes de programación como PHP donde los archivos de cabecera no existen, los comentarios de documentación se ponen justo arriba de la declaración de los elementos.

Ejemplo de documentación para doxygen en C

/**
* @brief Esta es una descripción corta para el archivo
*
* Descripción larga explicando que hace el código
* Se pueden describir parámetros como @p parametro1 y @p parametro2
*
* @author Rogelio Torres Baltazar
* @version 1.0
* @date 25/02/2014
* @warning Este es un código de ejemplo, no debe tomarse en serio
*/
#ifndef DISTOR_MAIN
#define DISTOR_MAIN

#include "General.h"

/**
* @brief Descripción breve de este macro
*
* Descripción detallada de este macro
*/
#define ALSA_PCM_NEW_HW_PARAMS_API


#include "RingMng.h"
#include "Capture.h"
#include "PlayBack.h"
#include "stdio.h"
#include "stdlib.h"
#include "string.h"
#include "pthread.h"
#include <alsa/asoundlib.h>


/**
* @brief Función que se encarga de de capturar el audio
*
* Esta es una descripción más detallada de la función que se encarga de capturar
* el audio
*/
void CaptureThread();

#endif

Ejemplo de documentación para doxygen en PHP

<?php
/** 
* @brief Descripción corta de la clase PHP
* @author Rogelio Torres Baltazar
* @date Febrero del 2014
*/
class Register extends CI_Controller {

    /**
    * constructor de la clase
    */
    public function __construct()
    {
        parent::__construct();
        $this->load->library('session');
        $this->load->helper('url');
        $this->load->database();
        $this->load->library('form_validation');
        $this->config->set_item('language', 'spanish');
        $this->load->helper('template_helper');
    }

    /**
    * @brief descripción corta del metodo index()
    *
    * Descripción detallada del metodo index()
    * @param $dato - el parámetro que recibe la función index()
    */
    public function index($dato)
    {
        if(!$this->session->userdata('logged_in'))
        {
            add_css('register');
            add_js('jquery');
            add_js('jquery-validation/dist/jquery.validate.min');
            add_js('register');
            $this->load->view('header');
            $this->load->view('register/register');
            $this->load->view('footer');
        }
        else
        {
            redirect('/');
        }
    }
}

Como se ve en los ejemplo anteriores, existen diferentes comandos que se pueden poner en la documentación para darle instrucciones y más información a Doxygen. Estos comandos se usan anteponiendo bien el símbolo de barra invertida () o el símbolo de arroba (@) al nombre del comando.

Algunos comandos existentes son @a, que sirve para poner palabras en fuente cursiva, @author, que sirve para especificar un autor de lo que se esta documentando.

Se puede ver la lista completa de comandos en la siguiente pagina y su descripción: http://www.stack.nl/~dimitri/doxygen/manual/commands.html

¿Como funciona Doxygen?

En términos generales, analiza los archivos fuente de una ubicación o carpeta que se le indique, y dependiendo de los parámetros de configuración que se hayan establecido, el programa generará la documentación en el formato o formatos especificados.

Para generar la documentación tan solo es necesario ejecutar el comando

$doxygen archivoDeConfiguracionDelProyecto

Doxygen automáticamente detecta el código documentado y genera el archivo de documentación correspondiente, opcionalmente se puede configurar Doxygen con el parametro “EXTRACT_ALL”para que documente todos los archivos del proyecto(documentados y no documentados), y genere documentación básica para todos, esto es, analice la estructura del código y reconozca y liste macros y funciones, permitiendo así tener una mejor visualización y control de todos los archivos de un proyecto.

Archivo de configuración de Doxygen

Para indicarle la ruta o rutas de un proyecto a Doxygen, y todos los demás parámetros de configuración, se debe de crear un archivo de configuración doxygen para cada proyecto.

De esta forma, tan solo basta ejecutar en la terminal el comando

$doxygen archivoDeConfiguracionDelProyecto

para generar la documentación del proyecto, donde “archivoDeConfiguracionDelProyecto” es el archivo de configuración para doxygen del proyecto.

El archivo de configuración tiene una estructura del tipo clave = valor1 valor2 …

Ejemplo:

DOXYFILE_ENCODING      = UTF-8

PROJECT_NAME           = Notas de software

PROJECT_NUMBER         = 1

Doxygen nos permite generar un archivo de configuración automáticamente con parámetros por defecto, que nos sirve para la mayoría de los casos.

Para generar el archivo de configuración para Doxygen por defecto tan solo necesitamos ejecutar en la terminal el comando:

$doxygen -g <nombreArchivoConfiguracion>

donde <nombreArchivoConfiguracion> es el nombre que se le dará al archivo de configuración creado.

Una vez creado el archivo lo podemos inspeccionar con cualquier editor de texto plano.

Parámetros importantes del archivo de configuración

Cabe destacar ciertos parámetros importantes en el archivo de configuración que vale la pena echar un vistazo.

PROJECT_NAME           = “My Project”
Con esta parámetro indicamos el nombre de nuestro proyecto, por defecto doxygen le asigna el nombre de “My Project”

OUTPUT_DIRECTORY       =
Nos permite indicar el directorio donde se generaran los archivos de documentación, si se deja vacío, como viene por defecto, la documentación se generara en el mismo directorio del proyecto.

Admite poner rutas absolutas o relativas al directorio del proyecto.

EXTRACT_ALL            = NO
Este parámetro nos permite indicarle a doxygen que documente o no, todos lo archivos del proyecto, incluidos los archivos a los que no se le ha agregado ninguna comentario especifico de documentación.

Si este parámetro se pone como YES, doxygen analizara la estructura de funciones y macros de todos los archivos y generara documentación básica para todos ellos, esto es muy util para tener un control de todos los archivos que componen el proyecto.

Instalando Doxygen en Mac

Instalar Doxygen en mac es tan fácil como instalar cualquier otro programa, nos vamos a la página oficial de doxygen: http://www.stack.nl/~dimitri/doxygen/download.html , descargamos el archivo .dmg. y copiamos el contenido del paquete a nuestra carpeta de aplicaciones.

Una vez con la aplicación de Doxygen instalada, agregamos un link para poder utilizarla más fácilmente. En la terminal escribimos:

$sudo ln -s /Applications/Doxygen.app/Contents/Resources/doxygen /usr/local/bin

Haciendo esto podemos utilizar doxygen con el comando $doxygen en la terminal

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *