Tutorial del doc++

Por J. J. Merelo Guervós

Página principal del curso de C++
Otros cursos y tutoriales: comercio electrónico, WAP, Webmaster
Tutorial de C++ Avanzado
Página principal del grupo GeNeura

Presentación del DOC++

DOC++ es un sistema de documentación para C/C++ y Java, que documenta el código tanto en LaTeX (para documentaciones más profesionales) como en HTML (para publicar en la web). La documentación se crea directamente a partir de las cabeceras de los ficheros C++ o Java.

A continuación podemos ver una lista de características del sistema:

Introducción

La idea del doc++ es proporcionar una herramienta que permita al programador escribir documentación de alta calidad, y para ello lo mejor es que se pueda incluir la documentación dentro del mismo código fuente, sin tener que mantener ficheros externos aparte de las fuentes del programa. A la vez, esta documentación debe de estar incluida de tal forma que se pueda compilar directamente el código, sin necesidad de preproceso, por ello, la única solución es ponerlo dentro de los comentarios de C++.

Eso es precisamente lo que doc++ usa para generar la documentación; de hecho, usa el mismo modelo que javadoc, el sistema automático de documentación de programas en Java: incluir órdenas para la documentación automática dentro de comentarios especiales (aunque javadoc usa los comentarios normales). Algunos comentarios se refieren directamente al c&oacue;digo, mientras que otros tratan con asuntos más amplis. En doc++, la documentación tiene el siguiente formato:

/** ... */
///

El primero sirve para comentarios que ocupen varias líneas, el segundo para los que ocupen una sola línea

Para que la documentación sea de alta calidad, debe de ser fácil navegar por ella, y además poderse generar directamente un manual de referencia con buena pinta. doc++ hace las dos cosas: genera documentación en HTML con un applet bastante chulo para navegar por la jerarquía de clases, y además genera documentación en LaTeX (procesador de textos disponible en todas las máquinas Linux y en muchos Unix). La jerarquín de clases sirve para estructurar la documentación en secciones y subsecciones.

Además de la jeraquía de clases, también se puede imponer otra estructura sobre la documentación, agrupándola en secciones y subsecciones.

doc++ también tiene defectos: el principal es que se ha dejado de desarrollar, y hay otros sistemas de documentación que aún siguen desarrollándose, entre ellos perceps, y otros. Además, tiene algunos errores: corta algunos nombres de variables, por ejemplo. Sin embargo, por el momento es la mejor alternativa.

Para empezar

Lo mejor es comprobar si doc++ está instalado en tu sistema; si no lo está, hace falta bajárselo de http://www.imaginator.com/doc++ o de alguno de los mirrors. También hay una referencia a él en FreshMeat. Compilarlo para Linux no presenta ningún problema; una vez compilado hay que instalarlo donde suelan ir los ejecutables en el sistema. También se puede compilar sin problemas para Win95/98/NT usando el compilador incluido en el entorno CygWin, disponible en el sitio web de Cygnus.

Una vez instalado, basta añadir /// en la línea anterior a cada función que se quiera documentar, o bien, si se quiere escribir más de una línea de documentación, lo siguiente

/** 
Este es un comentario mu chulo
*/

si se van a escribir más de una línea de comentario. O bien se puede llamar al programa docify para que lo haga, de la forma siguiente

bash$ docify miprograma.cpp miprograma.doc.cpp

que automáticamente añade esos comentarios especiales delante de cada funci&oacue;n, clase y todo lo que pille. No es muy aconsejable, salvo para darse cuenta de cómo va el tema, porque añade demasiados comentarios a demasiadas cosas. Por ejemplo, una clase comentada con doc++ podría ser esta:

/// Esta es una clase chula que he hecho yo
class miClase {
public:
    /// Esto parece el constructor y lo es
    miClase() {};

    /// Y esto no puede ser otra cosa que el destructor
    ~miClase() {};

    /** Y esto es una funcion que sirve para chulearme.\\
    Como este comentario es mu importante, lo divido en muchas\\
    lineas*/
    void funcionMuImportante( tipoVar _miVar );
};

/// Y esta es una clase shiquitiya que desciende de la anterior
class miSubclase: public miClase{};

Una vez hecha cualquiera de las dos cosas (comentarios a mano o con el docify, ya se puede usar doc++

bash$ doc++ -d html miprograma.cpp

si se quiere generar documentación en HTML en un directorio llamado html, o

bash$ doc++ -t -o miprograma.tex miprograma.cpp

Si se han puesto comentarios en varios ficheros, también se puede usar

bash$ doc++ -d html *.cpp

Una vez hecho eso, se puede usar directamente el navegador (siempre que contenga Java, y que le funcione correctamente, no como en ciertas máquinas que yo me sé), de esta forma:

bash$ netscape html 

o bien,

bash$ netscape html/index.html 

que es tres cuartos de lo mismo. Si no casca el navegador con el Java, se verá algo así.

Es decir, cada comentario especial genera una página de manual. Si se quieren agrupar las entradas del manual, por ejemplo, para agrupar varias clases que se parezcan una a otra, o los constructores y destructores, se usa lo siguiente:

/**@name 
 
//@{

//@}

Como por ejemplo

/**@name Mis clases favoritas
Estas clases las he hecho como ejemplo del tutorial
*/
//@{
/// Esta es una clase chula que he hecho yo
class miClase {
    public:
    

    /**@name Constructores y destructores */

    //@{

    /// Esto parece el constructor y lo es
    miClase() {};

    /// Y esto no puede ser otra cosa que el destructor
    ~miClase() {};

    //@}

    /** Y esto es una funcion que sirve para chulearme.\\
    Como este comentario es mu importante, lo divido en muchas\\
    lineas*/
    bool funcionMuImportante( tipoVar _miVar );
};

/// Y esta es una clase shiquitiya que desciende de la anterior
class miSubclase: public miClase{};
//@}

que generaría una página como la siguiente . También se pueden inclur ficheros usando la orden

//@include: 

Como por ejemplo

//@include: miClase.h miSubclase.h

Normalmente estos comentarios especiales irán en los ficheros de cabecera, y hay que tener cuidado de no repetirlas en los ficheros de implementación (los .cpp, si los hubiere), porque si no aparecerán las entradas del manual repetidas. Lo mejor en estos casos es sustituir los comentarios especiales del doc++ por comentarios normales.

Algunas instrucciones de uso

doc++ tiene muchas opciones posibles, que se pueden consultar en las páginas de manual o bien escribiendo doc++ -h. Algunas opciones útiles de línea de comandos son las siguientes:

Hay otras opciones para generar LaTeX, que no hay más que consultar en la página de manual correspondiente. Las anteriores, para el autor, son las más útiles y las que más se utilizan.

Hay otra serie de órdenes propias del doc++, que se incluyen dentro de los comentarios especiales. Fuera de los comentarios especiales, no las coge. Todas ellas van precedidas de nuestra querida @ (igual que en el javadoc); una ya la hemos visto, @name, que sirve para dar un nombre a un comentario o grupo de comentarios.

Con todo esto, ya se puede documentar del todo nuestra clase anterior

/**@name Mis clases favoritas
Estas clases las he hecho como ejemplo del tutorial
@author El Reverendo Horton Heat
@see miSubclase
*/
//@{
/// Esta es una clase chula que he hecho yo
class miClase {
public:
    /**@name Constructores y destructores*/

    //@{

    /// Esto parece el constructor y lo es
    miClase() {};

    /// Y esto no puede ser otra cosa que el destructor
    ~miClase() {};

    //@}

    /** Y esto es una funcion que sirve para chulearme.\\
    Como este comentario es mu importante, lo divido en muchas\\
    lineas
    @param _miVar esta variable se le pasa a la función y hace
    cosas con ella
    @return true si el universo se expande, false si se contrae
    @exception runtime_error si estamos dentro del horizonte de
    sucesos de un agujero negro*/
    bool funcionMuImportante( tipoVar _miVar );
};

Que daria una cosa así

Algunos consejos

Lo más aconsejable para estructurar la documentación de una librería o un programa es hacerlo a partir de un solo fichero. Como tal fichero puede servir, por ejemplo, el fichero que contiene todas las cabeceras de la libreria, como hace por ejemplo la STL. De esta forma, a la vez que se incluye el fichero usando una orden del preprocesador de C++ se puede incluir una orden de doc++ que incluiría la documentación correspondiente y la ordenaria jerarquicamente. Dentro de cada clase o jerarquía de clases, es tambi´n conveniente incluir un comentario con @name para subrayar los aspectos más importantes de la librería o programa. Podria quedar de la siguiente forma

/** @name Introduccion a la librería AcojoLib
Esta librería include las STL, GTK+, GL y es más chula que todas
ellas juntas.
@author Bill Gates y Linus Torvalds
*/
//@{
/**@name Tipos de datos abstractos
Sirven como base de las jerarquías y hay que saber como van*/
//@{
#include 
#include 
//@include ADT1.h ADT2.h
//@}
/**@name Clases derivadas
Son las clases derivadas con implementaciones integrales*/
//@{
#include 
#include 
//@include derivada1.h derivada2.h
//@}
//@}

Otro consejo es no confiar en que doc++ genere las cosas exactamente como queremos. Habitualmente hay que "depurar" la documentacion hasta que salga correctamente; es mejor hacer un proceso iterativo de escribir la documentación, probarla, modificarla y volverla a modificar hasta que salga bien.

Ejercicio Diseñar una clase e incluir todas las órdenes de doc++ posibles; incluir un pie personalizado.


manual sobre las posibilidades del DOC++Manual de Referencia

desarrollo de un ejemplo sencilloExample

problemas frecuentes y solucionesPosibles Problemas y Soluciones

Página principal del curso de C++
Otros cursos y tutoriales: comercio electrónico, WAP, Webmaster
Tutorial de C++ Avanzado
Página principal del grupo GeNeura