Documentation 在何处放置内部库的doxygen注释块-在H或CPP文件中？

常识告诉我们，Doxygen注释块必须放在类、结构、枚举、函数和声明所在的头文件中。我同意这是一个合理的论据，它支持在没有源代码的情况下分发库（只有带有目标代码的头和库）

但是……当我开发一个公司内部（或作为我自己的一个附带项目）库时，我一直在考虑完全相反的方法，该库将与它的完整源代码一起使用。我的建议是在实现文件（HPP、INL、CPP等）中放置较大的注释块，以避免使标头中声明的类和函数的接口混乱

优点：

• 头文件中的混乱更少，只能添加函数的分类
• 例如，当使用Intellisense时预览的注释块不会冲突-这是我在.H文件中有一个函数的注释块，并且其内联定义在同一个.H文件中，但包含在.INL文件中时观察到的一个缺陷

缺点：

• （显而易见的一个）注释块不在声明所在的头文件中

那么，你有什么想法和可能的建议呢？

标题： 更容易阅读注释，因为查看文件时，其他“噪音”更少

资料来源： 然后，您可以在查看注释时阅读实际函数

我们只使用标题中注释的所有全局函数和源代码中注释的局部函数。如果需要，还可以包括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将函数/方法文档中的所有内容分组。

我将所有内容都放在头文件中

---

我记录所有内容，但通常只提取公共接口。

在标题中包含注释意味着如果注释发生更改，必须重新编译类的所有用户。对于大型项目，如果程序员冒着花20分钟重建所有内容的风险，他们将不太倾向于更新标题中的注释

---

和。。由于您应该阅读html文档，而不是浏览文档代码，因此在源文件中更难找到注释块并不是什么大问题

将文档放在人们使用和编写代码时阅读和编写的地方

类注释在类前面，方法注释在方法前面

---

这是确保事物得到维护的最佳方式。它还使头文件相对精简，避免了人们更新方法文档导致头文件变脏和触发重建的棘手问题。事实上，我知道有人用它作为以后编写文档的借口

我喜欢利用名称可以在多个地方记录的事实

在头文件中，我写了一个方法的简要描述，并记录了它的所有参数——这些参数与方法本身的实现相比不太可能改变，如果改变了，那么在任何情况下都需要改变函数原型

我将长格式文档放在实际实现旁边的源文件中，因此可以随着方法的发展更改细节

例如：

mymodule.h

//@brief此方法将两个整数相加。
///@param是要添加的第一个整数。
///@param b要添加的第二个整数。
///@返回两个参数的总和。
整数相加（整数a、整数b）；

mymodule.cpp

///此方法使用一种鲜为人知的整数加法变体，称为
///索福克勒斯剪刀。它在许多方面优化了功能的性能
///我们将来可能选择或不选择的目标平台。
///@TODO确保我通过一些单元测试正确实现了算法。
整数相加（整数a，整数b）{
返回b+a；
}

我正在使用QtCreator进行编程。一个非常有用的技巧是按Ctrl键单击函数或方法以在头文件中获取声明

---

当在头文件中对该方法进行注释时，您可以快速找到要查找的信息。所以对我来说，注释应该位于头文件中我有一个痛苦的提醒，为什么应该避免头文件中的文档-一位高级副总裁告诉我将方法注释放入类声明中，我发现自己实际上在为类声明保存注释编辑稍后，因为点击这些标题会触发45分钟的构建时间！不是向下投票，只是提问：如果我想弄清楚API（甚至是内部API）的功能，我宁愿不打开.cpp并费力地浏览所有代码来查找文档。我承认，如果您记录的不仅仅是客户对该方法正在做什么的看法（比如它是如何做的），那将是一件痛苦的事情，但无论如何您不应该这样做，对吗？使用Doxygen生成文档的全部目的是让生成的文档可以访问。我们有一个内部的w