常识告诉我们，Doxygen注释块必须放在类，结构，枚举，函数，声明所在的头文件中。我同意这是一个合理的论据，对于没有源的库（仅包含目标代码的标头和库）来说，这是合理的。
但是...在开发公司内部（或作为我自己的副项目）库时，我一直在想完全相反的方法，该库将与其完整的源代码一起使用。我建议将大注释块放在实现文件（HPP，INL，CPP等）中，以免使标头中声明的类和函数的界面混乱。
优点：
缺点：
那么，您如何看待并可能提出建议？
Answers:
将文档放在人们使用和处理代码时可以读写的地方。
类注释放在类前面，方法注释放在方法前面。
这是确保事物得到维护的最佳方法。它还可以使您的头文件保持相对的精简，并避免了人们更新方法文档的麻烦问题，这些问题导致头文件变脏并触发了重建。我实际上已经知道有人以此为借口以后编写文档！
我喜欢利用名称可以在多个地方记录的事实。
在头文件中，我编写了该方法的简短说明，并记录了其所有参数-与方法本身的实现相比，这些参数更改的可能性较小，如果存在，则无论如何都需要更改函数原型。
我将长格式文档放在实际实现旁边的源文件中，因此可以随着方法的发展而更改详细信息。
例如：
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分钟重建所有内容的风险，他们将不太愿意更新标头中的注释。
并且..由于您应该阅读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*/}
现在，您在两个功能上都获得了相同的文档。
这样一来，在最终输出中的多个位置显示文档的同时，您就可以减少代码文件中的干扰。