Doxygen permite documentar software a través de comentarios en el código fuente. Se ayuda de comandos especiales para agregar estructura, referencias y diseño a la documentación.
Si no conoce Doxygen se recomienda leer: comenzando con Doxygen
Introducción
Todos los comandos en la documentación comienzan con una barra invertida () o un signo de arroba (@). Todos los comandos que comienzan con una barra invertida pueden ser intercambiados por sus homólogos que comienzan con una arroba.
Algunos comandos tienen uno o más argumentos . Cada argumento tiene un cierto rango:
<> Si los signos de mayor que y menor que son usados para describir el argumento, el rango del argumento es una sola palabra después del comando.
Ej: comando <argumento>
comando valor_del_argumento este texto ya no forma parte del argumento
() Si se usan paréntesis para describir el argumento, el rango del argumento es la linea donde se escribió el comando.
Ej: comando (argumento)
comando esta linea completa es el argumento del comando
esta linea ya no es argumento del comando
{} Si se usan llaves para describir el argumento, el rango del argumento se extiende hasta el siguiente párrafo. Los párrafos son delimitados por una linea en blanco o por un indicador de sección.
Ej: comando {argumento}
comando esta linea forma parte del argumento del comando
Esta linea también forma parte del argumento del comando
Esta linea ya no forma parte del argumento del comando.
Se pueden usar corchetes [] sobre los símbolos anteriores para indicar que el argumento es opcional
Ejemplo: comando [<argumento>] se puede usar como
comando argumento
o simplemente:
comando
Lista de comandos
Indicadores estructurales
addtogroup <nombre> [(titulo)]
Define un grupo como lo hace el comando defgroup, a excepción de que no arrojará ninguna advertencia si se usa el mismo “nombre” más de una vez, sino que se fusionara con el ya existente y se usará el primer título encontrado en la documentación.
Ya que el titulo es opcional, este comando puede usarse para agregar nuevas entidades a un grupo existente utilizando @{ y @}
Ejemplo:
/*! addtogroup migrupo
* Documentación adicional para el grupo 'migrupo'
* @{
*/
/*!
* Una función
*/
void func1()
{
}
/*! Otra función */
void func2()
{
}
/*! @} */
page <nombre> (título)
Indica que ese bloque de comentario es documentación que no esta relacionada con una clase, archivo o función. El generador de documentación HTML creará una página aparte para ese pedazo de documentación. El generador de documentación Latex crea una nueva sección en el capitulo “Documentación de páginas” (page documentation)
Ejemplo:
/*! page pagina1 Una página de documentacion tableofcontents Titulo de encabezado section seccion Una sección de ejemplo Esta página contiene las sub-secciones ref sub-seccion1 and ref sub-seccion2 Para mayor información ve la pagina ref pagina2. subsection sub-seccion1 La primera sub-seccion Texto. subsection sub-seccion2 La segunda sub-seccion Más texto. */ /*! page pagina2 Otra pagina Más información */
Nota:
El argumento <nombre> consiste en una combinación de letras y números. Si se quiere usar mayúsculas o una combinación de minúsculas y mayúsculas el parámetro CASE_SENSE_NAMES debe tener un valor de YES. De cualquier manera, esto es solo posible si el sistema de archivos permite la utilización de mayúsculas. Se recomienda utilizar siempre minúsculas por cuestiones de portabilidad.
Indicadores de sección
attention { texto importante }
Inicia un párrafo que requiere atención debido a su importancia. El texto sera identado y resaltado con un diseño diferente. El texto no requiere ninguna estructura especial y se pueden usar comandos para mejoras visuales dentro de él. Muchos comandos adyacentes attention se concatenarán en un solo párrafo. El comando termina cuando se encuentra una linea en blanco u otro comando especial.
Ejemplo:
<?php
class Register extends CI_Controller {
/**
* Constructor de la clase
* attention Este mensaje es muy importante
* y debe ser resaltado del resto
*
* El constructor no acepta parámetros
*/
public function __construct()
{
parent::__construct();
}
}
Este código generará algo parecido a esto:
author { lista de autores }
Inicia un párrafo en donde se mostrarán uno o más autores. El párrafo tendrá un estilo identado. La lista de autores no requiere de ninguna estructura especial. Se pueden usar comandos para mejoras visuales en la lista de autores. Varios comandos author adyacentes serán unidos en un solo párrafo. Cada comando author adyacente inicia un salto de linea en el párrafo, pero tambien se pueden poner a varios autores en un solo comando author.
Ejemplo:
/*!
* brief Clase bonita
* details Esta clase se usa para demostración de comandos
* author Rogelio Torres
* author Juan Alvarez
* version 4.1a
* date 1990-2011
* pre Primero inicializa el sistema
* bug No toda la memoria es liberada cuando se borra el objeto
* warning Un mal uso de la clase puede afectar el rendimiento de tu aplicación
* copyright GNU Public License.
*/
class ClaseBonita {};
authors { lista de autores }
Equivalente a author
brief { descripción breve o corta }
Inicia un párrafo que denota una descripción corta. En archivos y clases la descripción corta sera usada en listas y en el principio de la página de documentación del archivo. Para elementos de archivos (una clase, una función) la descripción corta se ubicará antes de la declaración del elemento y de la descripción detallada.
La descripción breve termina cuando es encontrada una linea en blanco u otro comando de Doxygen. Si varios comandos brief son encontrados, estos se concatenaran para formar una sola descripción corta.
brief es sinónimo de short
bug { descripción del bug }
Comienza un párrafo en donde uno o mas “bugs” serán reportados. El párrafo tendrá un diseño indentado. El texto del párrafo no necesita ninguna estructura especial. Se pueden usar comandos para mejoras visuales dentro de la descripción del bug. Si se encuentran muchos comandos bug adyacentes, se concatenarán como uno solo pero cada nueva descripción comenzará en una linea diferente. El comando termina cuando se encuentra una nueva linea en blanco o cuando un comando de sección es encontrado.
Ejemplo: Un ejemplo se puede ver en la descripción del comando author
return {descripción del valor de retorno}
Describe un valor de retorno de una función. La descripción del valor de retorno no necesita de ninguna estructura especial.Se pueden utilizar comandos para mejoras visuales dentro de la descripción del valor de retorno. La descripción del valor de retorno termina cuando se encuentra una linea en blanco u otro comando de Doxygen. Si se encuentran varios comandos return en una linea, las descripciones de retorno se concatenarán.
returns {descripción del valor de retorno}
Equivalente a return
todo {párrafo describiendo que es lo que se debe hacer}
Inicia un párrafo en donde se describe una tarea que esta pendiente por hacer. La descripción también sera agregada a una lista independiente en donde están todas las cosas por hacer. Las descripciones de la lista y la documentación estarán ligadas. Cada item en la lista de cosas por hacer tendrá una cabecera con un enlace al origen de la nota.
Comandos para mejoras visuales
a <palabra>
Muestra el argumento <palabra> en italica o cursiva. Use este comando para enfatizar palabras.
Ejemplo:
... las coordenadas a x e a y son usadas para ..
Esto genera una salida:
… las coordenadas x e y son usadas para …
arg { descripción-del-item }
El argumento de este comando se extiende hasta la primera linea en blanco u otro comando de tipo arg que se encuentre.
Este comando se usa para generar una lista no anidada simple de argumentos. Cada argumento debe ser precedido por el comando arg
Ejemplo:
Si se escribe:
arg c Cantidad cantidad de elementos. arg c Color color de los elementos. arg c Dirección dirección de los elementos. El método no admite sobrecarga
El resultado será el siguiente:
- Cantidad cantidad de elementos
- Color color de los elementos
- Dirección dirección de los elementos
El método no admite sobrecarga
b <palabra>
Muestra el argumento <palabra> en negritas. Equivalente a <b> palabra </b> Para poner varias palabras en negritas se usa <b> palabra1 palabra2 </b>
c <palabra>
Muestra el argumento <palabra> utilizando una fuente de maquina de escribir. Use este comando para referirse a una palabra de un código.
Ejemplo:
Si escribimos:
... Esta función retorna c void y no c int ...
Obtendremos:
… Esta función retorna void y no int
Comandos para crear enlaces
addindex (texto)
Este comando agrega el (texto) al indice de Latex
anchor <palabra>
El nombre de este comando puede ser traducido como ancla.
Este comando pone un ancla o referencia invisible en el documento a la cual se puede hacer referencia después con el comando ref
Nota: Las referencias o anclas solo pueden ser puestas en bloques de comentarios que han sido marcados como páginas (con el comando page) o páginas principales(mainpage)