何处放置内部库的doxygen注释块 – 在H中还是在CPP文件中？
常识告诉Doxygen注释块必须放在类，结构体，枚举，函数，声明所在的头文件中。 我同意，这是一个很好的参数，意思是没有它的源代码的分发（只有头文件和库和目标代码）。
但是…当我正在开发公司内部（或作为自己的一个项目）库时，我一直在考虑完全相反的方法，它将被用于完整的源代码。 我所build议的是在实现文件（HPP，INL，CPP等）中放置大的注释块，以避免混乱头中声明的类和函数的接口。
优点：
- 在头文件中更less的混乱，只能添加function的分类。
- 例如使用Intellisense时预览的注释块不会发生冲突 – 这是我在.H文件中为函数注释块时观察到的缺陷，并且其内联定义位于相同的.H文件中但是包含在.INL文件中。
缺点：
- （显而易见的）注释块不在声明的头文件中。
那么，你觉得和可能build议什么？
将文档放在人们正在使用和编写代码的地方读写。
类注释放在类的前面，方法的注释放在前面。
这是确保事情得到维护的最好方法。 它还可以保持头文件相对精简，并避免更新方法文档引起头部变脏并触发重build的碰触问题。 其实我已经知道人们以此为借口来编写文档了！
我喜欢利用名称可以在多个地方logging的事实。
在头文件中，我写了一个关于该方法的简短描述，并logging了它的所有参数 – 它们比方法本身的实现更不太可能改变，如果这样做，那么函数原型需要在任何情况下改变。
我将长格式的文档放在实际实现旁边的源文件中，所以细节可以随着方法的发展而改变。
例如：
mymodule.h
/// @brief This method adds two integers. /// @param a First integer to add. /// @param b Second integer to add. /// @return The sum of both parameters. int add(int a, int b); mymodule.cpp
/// This method uses a little-known variant of integer addition known as /// Sophocles' Scissors. It optimises the function's performance on many /// platforms that we may or may not choose to target in the future. /// @TODO make sure I implemented the algorithm correctly with some unit tests. int add(int a, int b) { return b + a; }
在头文件中有注释意味着如果一个注释被改变，则必须重新编译一个类的所有用户。 对于大型项目，如果编码人员冒着花费接下来的20分钟重build所有东西的风险，他们将不会倾向于更新标题中的评论。
而..因为你应该阅读的HTML文件，而不是浏览代码文件，这不是一个大问题，注释块更难以在源文件中定位。
标题：更容易阅读评论，因为在查看文件时有更less的其他“噪音”。
资料来源：然后你有实际的function可供阅读，同时看着评论。
我们只是使用在源代码中注释的标题和本地函数中注释的所有全局函数。 如果你想，你也可以包括copydoc命令插入多个地方的文档，而不必多次写（更好的维护）
然而，您也可以通过一个简单的命令将结果复制到不同的文件文档中。 例如： –
我的file1.h
/** * \brief Short about function * * More about function */ WORD my_fync1(BYTE*);
我的file1.c
/** \copydoc my_func1 */ WORD my_fync1(BYTE* data){/*code*/}
现在你得到两个函数相同的文档。
这样可以减less代码文件中的噪音，同时在最终输出的几个地方得到的文档写在一个地方。
通常我将.h文件中的接口（\ param，\ return）的文档和.c / .cpp / .m文件中的实现文档（\ details）放在一起。 Doxygen将函数/方法文档中的所有内容分组。
我把所有的东西放在头文件中。
我logging了一切，但只是一般地提取公共接口。
我正在使用QtCreator进行编程。 一个非常有用的技巧在于按住Ctrl键单击一个函数或方法来获取头文件中的声明。
当头文件中评论该方法时，可以快速find您要查找的信息。 所以对我来说，注释应该位于头文件中！
在c ++中，有时可以在头文件和.cpp模块之间进行拆分。 这里把它的文档放到头文件中似乎比较干净，因为这是所有公共函数和方法的唯一保证。
