How to use Doxygen to document local variables within C++ functions

Question

For example, in my function

//starting code with doxygen documentation
/** The main function. I will now try to document variables within this main function*/
int main()
{
 int arr[]; /** \brief an integer array*/
 .....
 return 0;
}
//end of code

However, when I use Doxygen with the "HIDE_IN_BODY_DOCS" variable set to "NO" in the configuration file, this does not perform specific documentation for this local variable. Rather, it just takes that bit and prints it along with the function documentation, as if it were any other comment line within the function

How can I document such local variables using Doxygen?

Answer 1

I do not know a way to do that (and I do doubt that there exists a way). Remember, that doxygen was made to document classes and function headers, i.e. 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. However, as you are programming in C(++), it should not be a problem to document local variables in source. Just give it a proper name or document it "in source":

Cat cats[]; // holds a bunch of cats

In languages where you define all your variables must be declared at the beginning of your function(Delphi, Pascal), the system demanded by you would make sense though.

Answer 2

While you can put comments in the body of a function and let them appear as part of the function documentation like so

/** @file */

/** The main function. I will now try to document 
 *  variables within this main function.
 */
int main()
{
  /** an integer array. */
  int arr[];

  /** An endless loop */
  for (;;) {}

  return 0;
}

This is generally not recommended as others already pointed out. If you want (as a developer) to read the sources along with the documentation, you can better use normal C comments in the body

/** @file */

/** The main function. I will now try to document 
 *  variables within this main function.
 */
int main()
{
  /* an integer array. */
  int arr[];

  /* An endless loop */
  for (;;) {}

  return 0;
}

along with setting INLINE_SOURCES to YES.