Documenting variables with Doxygen in C

2013-02-28

An answer to this question on Stack Overflow.

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

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