Documenting functions in C++ with Doxygen [closed]

Question

I've got a project that I'm using Doxygen to generate documentation for. The documentation of the classes is fine, but I've also got some non-member functions that I use to create objects etc. I'd also like to have these documented, but no matter what I try, Doxygen will not generate documentation from the comments that I have placed above the functions. Why won't Doxygen generate documentation for functions in the global namespace, and what do I need to do to get this to work?

Answer 1

Use \fn where you otherwise use \class in your \\*! *\ block

http://www.doxygen.nl/manual/docblocks.html look for "Documentation at other places"

http://www.doxygen.nl/manual/commands.html#cmdfn
It works similar as documenting member functions

Answer 2

Entities that are members of classes are only documented if their class is documented. Entities declared at namespace scope are only documented if their namespace is documented. Entities declared at file scope are only documented if their file is documented.

So to document a free function in the global namespace you also need a line like this somewhere in the header file in which it is declared:

/** @file */

Or like this:

/*! \file */

Answer 3

This pattern worked well for us.

/*! Convert counts to kg for the reservoir.  
    \param counts The A/D counts to convert.` 
    \return The calculated kg based on the parameter.  
*/  
float RES_ConvertCountsToValue(uint_16 counts);  

Answer 4

I like this pattern

   ///////////////////////////////////////////////////////////////////////
   /// \brief setX
   /// \param x offset of the image.
   /// \return a new image as an QImage.
   /////////////////////////////////////////////////////////////////////////
    QImage  setX(int x);