Documenting variables with Doxygen in C

Question

Code:

#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");
}

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

Answer 1

DOxygen was made to document classes and function headers or, in other words, the interface. Think of the documentation as something that other programmers study in order to use your classes and functions properly. You shouldn't use DOxygen to document your implementation. Instead, document your local variables in the source with // or /* */.

There are a number of ways to make comments in DOxygen, some examples of which (for member variables) can be seen in the manual here. I've copied them below.

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

Answer 2

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.