常识告诉 Doxygen 注释块必须放在类、结构、枚举、函数、声明所在的头文件中。我同意这是一个合理的论点，因为库的意思是在没有源代码的情况下分发（只有标头和带有目标代码的库）。
但是......当我开发公司内部（或作为我自己的副项目）库时，我一直在考虑完全相反的方法，该库将与其完整源代码一起使用。我建议将大的注释块放在实现文件（HPP、INL、CPP 等）中，以免弄乱标头中声明的类和函数的接口。
优点：
缺点：
那么，您有什么想法和可能的建议？
将文档放在人们在使用和处理代码时会阅读和编写的地方。
类注释在类前面，方法注释在方法前面。
这是确保事情得到维护的最佳方式。它还使您的头文件相对精简，并避免人们更新方法文档导致头文件变脏并触发重建的感人问题。实际上，我知道人们用它作为以后编写文档的借口！
我喜欢利用可以在多个地方记录名称的事实。
在头文件中，我写了方法的简要描述，并记录了它的所有参数——这些比方法本身的实现更不可能改变，如果他们这样做了，那么无论如何都需要改变函数原型.
我将长格式文档放在实际实现旁边的源文件中，因此可以随着方法的发展更改细节。
例如：
我的模块.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);
我的模块.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 分钟内重建所有内容的风险，他们将不太愿意更新标题中的注释。
而且.. 由于您应该阅读 html 文档而不是浏览文档代码，因此在源文件中更难找到注释块并不是一个大问题。
标题： 更容易阅读评论，因为在查看文件时其他“噪音”较少。
资料来源： 然后您可以在查看评论时阅读实际功能。
我们只使用在标头中注释的所有全局函数和在源代码中注释的局部函数。如果您愿意，还可以包含 copydoc 命令以将文档插入多个位置，而无需多次编写（更好地进行维护）
但是，您也可以使用简单的命令将结果复制到不同的文件文档中。例如：-
我的文件1.h
/**
* \brief Short about function
*
* More about function
*/
WORD my_fync1(BYTE*);
我的文件1.c
/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}
现在您获得了关于这两个函数的相同文档。
这可以减少代码文件中的噪音，同时将文档写在一个地方，呈现在最终输出的多个地方。
通常我将接口文档 (\param, \return) 放在 .h 文件中，将实现文档 (\details) 放在 .c/.cpp/.m 文件中。Doxygen 对函数/方法文档中的所有内容进行分组。
我把所有东西都放在头文件中。
我记录了所有内容，但通常只提取公共接口。
我正在使用 QtCreator 进行编程。一个非常有用的技巧是按住 Ctrl 键单击函数或方法以获取头文件中的声明。
当在头文件中注释方法时，您可以快速找到您要查找的信息。所以对我来说，注释应该位于头文件中！
在 c++ 中，有时可以在 header 和 .cpp 模块之间拆分实现。在这里，将它的文档放入头文件似乎更干净，因为这是唯一保证所有公共函数和方法的地方。