Mi documento

La manera de documentar el código se puede hacer de 3 maneras distintas:

Formato JavaDoc:
Consiste en un bloque de comentario de C, que comienza con 2 asteriscos (*); así:
```
/**
 * ... texto ...
 */
```
Formato QT:
Consiste en un bloque de comentario de C, la primera línea contiene un signo de exclamación (!); así:
```
/*!
 * ... texto ...
 */
```
Variante C++:
Cada línea comienza con 2 //, seguidos de uno adicional, así:
```
///
/// ... text ...
///
```

En los 2 primeros casos, los asteriscos intermedios son opcionales.

Todo lo que se encuente dentro de estos bloques será reconicido por el programa. Dentro de esos bloques deben ir comandos que son identificados por el programa, y con ellos se arma la documentación. Dichos comandos deben ir precedidos por los caracteres: \ o @.

Ejemplo:

/**
* \mainpage Mi Tarea
* \author Eduardo Gonzalez
* \date Abril-2004
*/

El comando \mainpage es para especificar el contenido de la página principal de la documentación.
A su vez, \author define al autor del código.
En tanto, \date define la fecha.

Documentando Funciones:

La documentación de una función no es necesario que este en el mismo código que la función. Doxygen tiene la capacidad de recorrer todos los archivos fuente (esto se especifica en la configuración) y busca en todos ellos la documentación las funciones.

El comando asociado es \fn, también es posible usar \var. Si la función tiene parámetros, estos se especifican con \param. Si se desea agregar una breve descripción de la función, se emplea \brief. Para explicar el valor de retorno se usa \return.

Ejemplo:

/** \fn int *crear_arreglo(int L)
* \brief Crea un arreglo de tamaño L
* \param L Tamaño del arreglo.
* \return Devuelve el puntero al arreglo. */

Explicación:
\fn es seguido por la declaración de la función a documentar
\param parametro explicación
\brief es seguido por un texto descriptivo, pueden ser de varias líneas.(termina con una línea en blanco o el comienzo de otro comando)
\return explicación

El comando \fn puede omitirse, si y sólo si, la documentación de la función está justo antes de la declaración de la misma.

Nota: el creador de Doxygen advierte que el uso de \fn puede llevar a errores, como la existencia documentación duplicada. Indica solo usarla cuando sea estrictamente necesario.

Ejemplo variables locales:

/** \fn int *crear_arreglo(int L)
* \brief Crea un arreglo de tamaño L
* \param L Tamaño del arreglo.
* \return Devuelve el puntero al arreglo.
*
* Aquí se puede colocar una explicación mas
* detallada de lo que hace la función,
* se pueden incluir descripciones de
* variables locales si se desea.
*/

Ejemplo variables globales:

/** \var int rango
* \brief variable global.....
*
* Especifica el rango del eje X en el grafico.
*/

El comando \var se puede omitir si el bloque está previo a la declaración de la variable.

Documentando Archivos:

Existe la opción de agregar documentación a un archivo en particular. De esta manera se generará una documentación exclusiva para dicho archivo. El comando es \file. Su forma de uso es la siguiente:

/** \file [archivo]
 * ... otros comandos ...
 */

El nombre del archivo es opcional, si se omite se considera el archivo que contiene el bloque. Además, se puede especificar la ruta completa (o parte de ella) de la ubicación del archivo.

Ejemplo:

/** \file heapSort.c
* \brief Funciones para algoritmo HeapSort.
*
* Bla bla bla...
*/

Es importante tener en cuenta que si hay alguna variable, función, estructura, etc. documentada dentro de un archivo que no posea el bloque \file, dicha documentación no se procesará a menos que en otro archivo esté también definida la función, variable, etc (y la opción EXTRACT_ALL = NO).

Agrupando:

Es muy probable que en un código hayan funciones que trabajan en conjunto para obtener un resultado, y sería ordenado que en la documentación esas funciones aparezcan relacionadas o agrupadas. Pués bien, Doxygen ofrece una solución para eso. Es posible agrupar una cantidad de funciones bajo algún criterio, y éstas aparecerán documentadas todas juntas en una página aparte.

El comando para esto es \defgroup. Además se emplea \ingroup para definir que funciones pertenecen a algún grupo determinado.

Sintaxis:

/** \defgroup nombre_grupo Titulo del Grupo
 * ... otros comandos ...
 */

nombre_grupo debe ser único.
Titulo del Grupo pueden ser varias palabras.

Existen 2 formas de agregar elementos al grupo:

Mediante \ingroup nombre_grupo:
Esto se especifica en el bloque de documentación de la función a agregar.

/** \var void func (int i, int j )
* ....
* ....
* ....
* \ingroup XXX
*/

Definir los bloques de las funciones posterior al bloque del grupo.

//** \defgroup XXX My Algorithm
* ....
* @{
*/

/** \fn int partition (int r)
* ....
* ....
*/

/** \fn int sort (int *A, int r)
* ....
*/

/**
* @}
*/

Todos los bloques de documentación de funciones que esten entre los signos {@ y @} se incluyen al grupo. Esto no impide que se agreguen más funciones por el método de \ingroup.

Adornos visuales

Doxygen posee comandos que su función es dar formato al texto de la documentación.
De esta manera hace que la presentación sea mas agradable.

Comando	Sintáxis	Descripción
\e	\e <palabra>	Escribe en cursiva
\a	\a <palabra>	Usa una fuente especial
\arg	\arg { descripcion }	Crea una viñeta
\b	\b <palabra>	En negrita
\c	\c <palabra>	Escribe con fuente de ancho fijo
\code \endcode	\code .... \endcode	El texto es tratado como código C/C++
\n	\n	Nueva línea
\f$	\f$ formula \f$	Escribe una fórmula en la línea
\f[	\f[ formula \f]	Escribe una fórmula, en una nueva línea y centrada

Las fórmulas deben estar escritas en formato para Latex.

Además, Doxygen soporta algunos códigos HTML. Sin embargo, no soporta todo tipo de código HTML. Para eso están los comandos \htmlonly y \endhtmlonly, con estos el texto delimitado se pasa tal cual a la página HTML resultante, y así la interpreta el navegador.Existen los comandos \latexonly, \manonly, etc.

Para mayor información acerca de los comandos de Doxygen, ver manual original en www.doxygen.org