lunes, 25 de octubre de 2010

[Documentación de Software] Doxygen - Parte 2

Estuve investigando un poco más acerca de Doxygen, y aprendí a utilizarlo. Más adelante voy a subir un video-tutorial. Por el momento, doy una explicación rápida.

Para que Doxygen te genera la documentación de forma correcta, hay que tener cierto formato para comentar los métodos, las clases, etcétera. Explicaré ese formato a través de unos ejemplos:

class Persona
{
    public:
        //! Descripción corta.
        /** Descripción detallada/larga.
        * \param abc: Parámetro que sirve para ...
        * \return Retorna a ...
        */
        int A(int abc);

        /**
        * \brief Descripción corta.
        * 
        * Descripción detallada. Este formato es equivalente al de arriba.
        * 
        * @param cba: ...
        * @return Retorna a la nada misma...
        */
        int B(int cba);
};

Este formato se usa tanto para describir clases, como para describir métodos, archivos, etc.

Además de "param", "brief", y "return", existen otras palabras clave utilizadas para documentar. Se puede establecer el autor, utilizando la palabra "author" seguida del nombre del autor. Hay varias, se encuentran todas en internet dando vueltas..

Después, se pueden emplear códigos html para extender el formato de las descripciones, ejemplos:

/**
* \brief Ejemplos de usos de html en descripciones.
*
* Si yo en una descripción detallada, quiero dejar un renglón, simplemente
* haciendo esto que acabo de hacer (tocar "enter" para cambiar de línea), 
* no funciona, simplemente Doxygen escribe todo contínuamente. Para que 
* Doxygen haga un salto de línea, hay que escribir la etiqueta: 
* Si deseo escribir un texto en negrita, simplemente lo encierro entre 
* texto en negrita. Para la cursiva, texto en cursiva.
* Otro ejemplo útil es el de listado:
* 
    *
  1. Item 1.
  2. *
  3. Item 2.
  4. *
  5. Item 3.
  6. *
*/

Bueno, por hoy llego hasta acá. Espero que la información haya sido útil. Saludos!

PD: el código de "Ejemplos de usos de html en descripciones" se buguea en el post porque utilizo códigos html, espero que igual sea entendible.

sábado, 23 de octubre de 2010

[Documentación de Software] Doxygen

Doxygen es una herramienta que permite especificar y documentar el código fuente del software que se esté programando.

Documentar software es algo fundamental que cada programador debería realizar. Yo programo desde hace varios años, y sé por experiencia que documentar el código fuente es muy importante. Me pasaba antes, en mis inicios en la programación, que estaba con infinitas ideas y comenzaba un proyecto, luego de un tiempo lo "pausaba" y comenzaba otro, y así sucesivamente. Luego de un tiempo, cuando quería volver al primero, se me complicaba muchísimo porque tenía que mirar el código para entender qué había hecho, para qué servía cada función, etc. Desde que empezé a documentar el software, ya no tengo ese problema.

Doxygen soporta varios lenguajes: C, C++, C#, Java, Objetive C, Python, PHP e IDL. Y además, es multiplataforma.

Se puede descargar gratuitamente desde su página oficial: http://www.stack.nl/~dimitri/doxygen/index.html

sábado, 2 de octubre de 2010

[C/C++ IDE] Code Blocks - Instalación en Windows y Ubuntu

Code Blocks es un entorno de desarrollo para el lenguaje C y C++. Es multiplataforma, tiene un motor dinámico de plugins, acepta varios compiladores (como el de Visual Studio o MinGW), etc. No me voy a detener en la descripción, los interesados pueden ver más información en wikipedia a través de este link.

Para instalarlo en Windows:
- Instalación
  1. Entrar en la página de Code::Blocks.
  2. Ir a Downloads, y luego a Binary releases.
  3. Ahí se ven dos enlaces de descarga, uno que dice codeblocks-10.05mingw-setup.exe y el otro que dice codeblocks-10.05-setup.exe. La diferencia entre estos dos es que el que dice MinGW viene con un compilador integrado, mientras que el que no dice contiene solamente el IDE, y nosotros nos tenemos que encargar de instalar y configurar un compilador.
  4. Instalarlo como a cualquier programa de Windows.
  5. Al abrirlo, si pide seleccionar un compilador, elegir MinGW.
  6. Y listo, ya tenemos el IDE instalado, ahora hay que proseguir con la actualización del mismo. Para ello, hay que cerrarlo y seguir los pasos de Actualización.

- Actualización

  1. Entrar al foro de Code::Blocks.
  2. Buscar en User Forums, la sección de Nightly builds, e ingresar.
  3. En esta sección, ingresar al post perteneciente al último build. Ejemplo, el día de hoy, 2/10/2010, la última versión que se puede ver es: The 19 september 2010 build (6608).
  4. Descargar la dll de mingw, la de wxWidget, y el último build del IDE. Descomprimir y copiar en el directorio de instalación del mismo, reemplazando los archivos existentes. Ejemplo de los links pertenecientes a estos tres archivos a descargar:
    • IDEhttp://prdownload.berlios.de/codeblocks/CB_20100919_rev6608_CC_BRANCH_win32.7z
    • MinGW dll: http://prdownload.berlios.de/codeblocks/mingwm10_gcc441.7z
    • WxWidget dllhttp://prdownload.berlios.de/codeblocks/wxmsw28u_gcc_cb_wx2810_gcc441.7z

Para instalarlo en Ubuntu:
- Desde el menú de instalación de aplicaciones:
  1. Buscar Code::Blocks en la sección de programación, marcar e instalar.
- Desde terminal:
Actualizar paquetes:
    $ sudo aptitude update
Instalación:
    $ sudo aptitude install codeblocks codeblocks-contrib
Es recomendable instalar también:
    $ sudo aptitude install build-essential gdb subversion
    $ sudo aptitude install automake autoconf libtool
    $ sudo aptitude install libgtk2.0-dev libxmu-dev libxxf86vm-dev
Para trabajar con wxWidgets GUI toolkit:
    $ sudo aptitude install libwxbase2.8-dev wx2.8-headers libwxgtk2.8-dev wx-common

Espero que esta información les haya servido. Saludos!