Documenting functions in C++ with Doxygen [closed]

C开发者_如何学Pythonlosed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 4 years ago.

Improve this 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?

---

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 */

---

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

---

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);  

---

I like this pattern

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