Começando com doxygen

Instalação ou configuração

Instruções detalhadas sobre como configurar ou instalar o doxygen.

Comentando seu código

Existem várias maneiras de marcar um bloco de comentários como uma descrição detalhada, para que esse bloco de comentários seja analisado pelo Doxygen e adicionado como uma descrição do item de código a seguir à documentação. O primeiro e mais comum são os comentários no estilo C com um asterisco extra na sequência inicial do comentário, por exemplo:

/**
 * … text …
 */
int dummy_var;

A próxima alternativa é usar o estilo Qt e adicionar um ponto de exclamação (!) após a sequência de abertura de um bloco de comentários no estilo C:

/*!
 * … text …
 */
void foo(void);

Uma terceira alternativa é usar um bloco de pelo menos duas linhas de comentário C++, onde cada linha começa com uma barra adicional ou um ponto de exclamação:

/// 
/// ... text ... 
///

ou

//! 
//! ... text ... 
//!

Algumas pessoas gostam de tornar seus blocos de comentários mais visíveis na documentação. Para isso, você pode usar o seguinte:

 /********************************************//** 
  * ... text 
  ***********************************************/

Observe as 2 barras para encerrar o bloco de comentários normal e iniciar um bloco de comentários especial.

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

Para estruturar e formatar a documentação gerada, o Doxygen disponibiliza um grande número (> 170) de comandos especiais. Todos os comandos na documentação começam com uma barra invertida () ou uma arroba (@).

Por exemplo

/**
 * \brief    A brief description in one short sentence.
 */

é equivalente a

/**
 * @brief    A brief description in one short sentence.
 */

Para a breve descrição também existem várias possibilidades:

Pode-se usar o comando \brief com um dos blocos de comentários acima. Este comando termina no final de um parágrafo, portanto, a descrição detalhada segue após uma linha vazia.

/** \brief Brief description. 
 * Brief description continued. 
 * 
 * Detailed description starts here. 
 */ 

Se JAVADOC_AUTOBRIEF for definido como YES no arquivo de configuração, então usar blocos de comentários no estilo JavaDoc iniciará automaticamente uma breve descrição que termina no primeiro ponto seguido por um espaço ou uma nova linha.

/// Brief description which ends at this dot. Details follow 
/// here. 

E finalmente aqui um exemplo para uma documentação completa de uma função com doxygen:

/**
 * \brief   The function bar. 
 *
 * \details This function does something which is doing nothing. So this text
 *          is totally senseless and you really do not need to read this,
 *          because this text is basically saying nothing.
 *
 * \note    This text shall only show you, how such a \"note\" section
 *          is looking. There is nothing which really needs your notice,
 *          so you do not really need to read this section.
 *
 * \param[in]     a    Description of parameter a.
 * \param[out]    b    Description of the parameter b.
 * \param[in,out] c    Description of the parameter c.
 *
 * \return        The error return code of the function.
 *
 * \retval        ERR_SUCCESS    The function is successfully executed
 * \retval        ERR_FAILURE    An error occurred
 */

errcode_t bar(int a, int b, int c)
{    
    /** More detailed description inside the code */
}

fonte e mais informações na página inicial do Doxygen