Documenting variables with Doxygen in C

Question

Code:

include

/*
 * \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");
}

This doesn't generate descriptions for iOne, iTwo and iThree although that was my intention. How do I fix this?

Answer 1

You need to open your comments as Doxygen comments with /**.

It may be clearer to do this, though:

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

This way you can change the name of the variable without breaking your documentation and it's also easier on other programmers who need to read your source code because the description of the variable is located next to it, not somewhere else in the file.