variables de Documentación con Doxygen en C

Question

Código:

#include <stdio.h> 

/* 
* \var int iOne 
* \brief Integer 1 
*/ 
/* 
* \var int iTwo 
* \brief Integer 2 
*/ 
/* 
* \var int iThree 
* \brief Integer 3 
*/ 

/** 
* \brief Imitates a sheep. 
*/ 
void sheep(); 

/** 
* \brief Main function for test code 
*/ 
int main() { 
    int iOne, iTwo, iThree; 
    iOne = 1; 
    iTwo = 2; 
    iThree = 3; 
    printf("%d %d %d", iOne, iTwo, iThree); 

    return 0; 
} 

void sheep() { 
    printf("Meeeh"); 
} 

Esto no genera descripciones de iOne, iTwo y iThree aunque esa era mi intención. ¿Cómo puedo solucionar esto?

Answer 1

Debe abrir sus comentarios como comentarios de Doxygen con /**.

Puede ser más clara de hacer esto, sin embargo:

int main() { 
    /** \brief Integer 1 */ 
    int iOne; 
    /** \brief Integer 2 */ 
    int iTwo; 
    /** \brief Integer 3 */ 
    int iThree; 
    /** ... and so on ... */ 
} 

De esta manera se puede cambiar el nombre de la variable sin romper su documentación y también es más fácil en otros programadores que necesitan para leer su código fuente, porque la descripción de la variable se encuentra al lado, no en otra parte del archivo.

Answer 2

DOxygen se creó para documentar las clases y los encabezados de funciones o, en otras palabras, la interfaz . Piense en la documentación como algo que otros programadores estudian para utilizar sus clases y funciones de manera adecuada. No debe usar DOxygen para documentar su implementación. En su lugar, documente sus variables locales en la fuente con // o /* */.

Hay varias maneras de hacer comentarios en DOxygen, algunos ejemplos de los cuales (para las variables de miembro) se pueden ver en el manual here. Los he copiado a continuación.

int var; /*!< Detailed description after the member */ 

int var; /**< Detailed description after the member */ 

int var; //!< Detailed description after the member 
     //!< 

int var; ///< Detailed description after the member 
     ///< 

int var; //!< Brief description after the member 

int var; ///< Brief description after the member