Documenting variables with Doxygen in C

Question

the 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 does not generate descriptions for iOne , iTwo and iThree , although that was my intention. How to fix it?

Answer 1

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

It may be clearer to do this:

 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 violating your documentation, and also easier for other programmers who need to read the source code, because the variable description is located next to it, and not somewhere else in the file.

Answer 2

DOxygen was made to document classes and function headers or, in other words, an interface . Think of documentation as what other programmers are learning to use your classes and functions properly. You should not use DOxygen to document your implementation. Instead, document your local variables in the source using // or /* */ .

There are several ways to make comments in DOxygen, some examples of which (for member variables) can be seen in the manual here . I 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