使用 Doxygen 记录 C++ 中的函数
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2794054/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Documenting functions in C++ with Doxygen
提问by Paul
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?
我有一个项目，我正在使用 Doxygen 为其生成文档。类的文档很好，但我也有一些用于创建对象等的非成员函数。我也希望将这些文档记录下来，但无论我尝试什么，Doxygen 都不会从中生成文档我放在函数上方的注释。为什么 Doxygen 不会为全局命名空间中的函数生成文档，我需要做什么才能使其工作？
采纳答案by Pieter
Use \fnwhere you otherwise use \classin your \\*!*\block
使用\fn您\class在\\*!*\块中使用的其他地方
http://www.doxygen.nl/manual/docblocks.htmllook for "Documentation at other places"
http://www.doxygen.nl/manual/docblocks.html寻找“其他地方的文档”
http://www.doxygen.nl/manual/commands.html#cmdfn
It works similar as documenting member functions
http://www.doxygen.nl/manual/commands.html#cmdfn
它的工作原理类似于记录成员函数
回答by Oktalist
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 */
回答by Bruce
This pattern worked well for us.
这种模式对我们很有效。
/*! Convert counts to kg for the reservtheitroad.
\param counts The A/D counts to convert.`
\return The calculated kg based on the parameter.
*/
float RES_ConvertCountsToValue(uint_16 counts);
回答by Lukasz Madon
I like this pattern
我喜欢这个图案
///////////////////////////////////////////////////////////////////////
/// \brief setX
/// \param x offset of the image.
/// \return a new image as an QImage.
/////////////////////////////////////////////////////////////////////////
QImage setX(int x);
