Introducción
Doxygen ofrece muchas más funcionalidades y modos de los aquí resumidos, no obstante estos son los más cómodos. Existen comandos especiales adicionales, otras formas de escribir los comentarios, distintos modos de agrupación… No obstante, se ha elegido lo más útil y sencillo. Sirva este tutorial también de estándar del modelo de documentación en código que usaremos. El tutorial de cómo generar la documentación en sus diferentes formatos se hará aparte, puesto que no interesa a todos.
Descripciones
Para cada elemento del código existen tres tipos de descripciones:
- Descripción Breve
- Descripción Detallada
- Descripción del cuerpo (sólo para funciones). Se trata de la concatenación de todos los comentarios existentes dentro de la función.
Es importante que todos los elementos relevantes en el código (miembros de clases, funciones, estructuras, atributos, variables significativas…) tengan tanto descripción breve como detallada, porque la breve se muestra bajo el nombre del objeto en la documentación generada, y sólo se ve la detallada una vez entras a los detalles de dicho objeto. Pero ojo, la descripción breve debe ser BREVE, o se descuadrará la documentación.
1. Descripción Detallada
/**
* Descripción detallada. Nótese el doble ** inicial. Con uno sólo es un comentario normal.
*/
2. Descripción Breve
/** @brief Descripción breve.
* Termina al final del párrafo.
*
* Esta parte ya es descripción detallada.
*/
Si los comentarios se van a situar tras el objeto a comentar, en lugar de antes -NADA RECOMENDABLE- el comentario debe incluir el símbolo “<” para indicar a doxygen que el comentario hace referencia al atributo anterior.
Uso de HTML
Doxygen soporta la inclusión de HTML en los bloques especiales de comentarios (los /**). Son útiles para formatear las descripciones, resaltar contenidos o realizar listas. Ojo, no todos los comandos HTML están soportados, si os váis a poner finos mirad despacio los que sí aquí: http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
Particularmente interesantes son:
<b>esto es negrita</b>
<i>esto es cursiva</i>
<code>Letra de imprenta</code>
<hr> <- Escribe una línea horizontal
<ol></ol> -> Inicia/cierra una lista ordenada (numerada)
<ul></ul> -> Inicia/cierra una lista no ordenada
<li>esto es un elemento de una lista, va dentro de “<ol>” o “<ul>”. </li>
<table></table> -> Inicia/cierra una tabla
<tr></tr> -> Inicia/cierra una fila dentro de una tabla
<td></td> -> Inicia/cierra una columna dentro de una tabla
&?acute -> sustituyendo ? por una vocal, obtienes una vocal acentuada.
Además, para poner comentarios invisibles dentro de los bloques de comentarios, se puede usar el estilo de HTML:
/** <!-- Este texto no se verá en la documentación final, pero puede ayudar
a los programadores. --> Esta parte sí se verá.
*/
Comandos de Descripción de Elementos
- @param[in] nombre_param descripción_param -> Hay que poner un param por parámetro recibido. Se puede indicar [in], [out] o [in,out].
- @return descripción
- @see -> Un see para cada otro miembro que se referencie
- @deprecated -> Indica que esta entidad está en desuso.
- @pre -> Indica la precondición de una entidad
- @post -> Indica la postcondición de una entidad
- @since fecha -> Indica desde cuándo (qué versión o fecha) está disponible algo.
- @throw excepción descripción
- @bug descripción
- @file descripción -> Documenta el fichero con una breve descripción.
Ejemplo 1
/**
* A test class. A more elaborate class description.
*/
class Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
Agrupaciones
Por último, Doxygen incluye varias formas de agrupación. Nos quedaremos con la más útil, agrupación por módulos. Se pueden agrupar diferentes atributos,variables, typedefs… en un grupo con algún contenido o semántica común, de tal forma que la documentación generada los ponga en un apartado especial. Por ejemplo, puedes crear un grupo “Watcher” donde meter todas las funciones relacionadas con la vigilancia de cambios.
- Definir un grupo: @defgroup id_unico Nombre_para_la_doc
- Añadir a un grupo: @ingroup id_de_grupo
El id del grupo puede ser un nombre cualquiera, siempre que no existan dos grupos con el mismo nombre. Para no escribir repetidamente @ingroup, si los elementos a añadir se encuentran seguidos, se pueden usar @{ y }@ para indicar el comienzo y el final de un grupo.
Ejemplo 2
/**
* @ingroup A
*/
extern int VarInA;
/**
* @defgroup IntVariables Global integer variables
*/
/*@{*/
/** an integer variable */
extern int IntegerVariable;
/*@}*/
....
/**
* @defgroup Variables Global variables
*/
/*@{*/
/** a variable in group A */
int VarInA;
int IntegerVariable;
/*@}*/
Apéndice A: Python
La generación de documentación en python es idéntica, salvo que los bloques especiales de comentarios deben comenzar con ## en lugar de /**. Si se utiliza el estilo de python para los comentarios de los bloques especiales, es decir, si se usa “””, los comandos especiales (@author, @return…) no están soportados por Doxygen, por lo que es recomendable usar ##.
Ejemplo 3 - Python
## Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
## Documentation for a class.
#
# More details.
class PyClass:
## The constructor.
def __init__(self):
self._memVar = 0;
## Documentation for a method.
# @param self The object pointer.
def PyMethod(self):
pass
## A class variable.
classVar = 0;
## @var _memVar
# a member variable
Información Adicional
En la web de doxygen existe mucha más información: http://www.stack.nl/~dimitri/doxygen/manual.html
