使用Doxygen与C，你是否评论函数原型或定义？或两者？

Question

我正在使用Doxygen和一些嵌入式C源代码。给定一个.c / .h文件对，你是否将Doxygen注释放在函数原型（.h文件）或函数定义（.c文件）上，还是在两个地方都复制它们？

当我在一个地方而不是另一个地方记录时，我遇到了Doxygen警告缺少评论的问题;这是预期的，还是我的Doxygen搞砸了？

Answer 1

对于公共API，我在声明中记录，因为如果不使用doxygen输出，用户通常首先查看。

我从来没有遇到只在一个地方记录的问题，但我用它与C ++;可能与C不同，尽管我对此表示怀疑。

[edit]永远不要写两次。决不。源代码文档也遵循DRY，特别是关于此类复制和粘贴转换。[/ edit]

但是，您可以指定是否需要warnings for undocumented elements。虽然这些警告在理论上看起来不错，但我的经验是，它们很快就会成为一种负担，而不是一种帮助。记录所有功能通常不是可行的方法（有这样的东西是冗余文档，甚至阻碍文档，特别是太多的文档）;良好的文档需要知识渊博的人花时间。鉴于此，这些警告是不必要的。

如果你没有资源来写好文件（金钱，时间，等等......），那些警告也无济于事。

Answer 2

引用我对这个问题的回答：C/C++ Header file documentation：

  

我为界面添加了文档   （参数，返回值，什么   函数确实）在接口文件中   （.h）和。的文档   实现（如何该功能   在实现文件中（.c，   .cpp，.m）。我写了一个概述   在宣布之前的课程，所以   读者有直接的基础   信息。

使用Doxygen，这意味着描述概述，参数和返回值的文档（\brief，\param，\return）用于记录函数原型和内联文档（{{1} }）用于记录函数体（您也可以参考我对该问题的回答：How to be able to extract comments from inside a function in doxygen?）

Answer 3

我经常使用Doxygen和C嵌入式系统。我尝试仅在一个地方为任何单个对象编写文档，因为重复将导致后来的混乱。 Doxygen会对文档进行一定程度的合并，因此原则上可以在.h文件中记录公共API，并在.c文件中记录它实际工作原理。我自己也试过不这样做。

如果将文档从一个地方移动到另一个地方会改变它产生的警告数量，这可能暗示声明和定义之间可能存在微妙的差异。例如，使用-Wall -Wextra编译代码是否干净？是否有宏在一个地方而不是另一个地方改变代码？当然，Doxygen的解析器不是一个完整的语言解析器，也有可能让它混淆。

Answer 4

我们仅评论函数定义，但我们将它与C ++一起使用 在两个地方写它是浪费时间。 关于警告，如果您的文档看起来不错，也许这是忽略此类警告的好方法。

Answer 5

我已经问过自己同样的问题，并且在浏览生成的html文档时，Doxygen实际上包含了相应.h文件中.c文件中的相同内联文档，这令人惊喜。因此，您不必重复您的在线文档，Doxygen足够聪明，可以在两个地方都包含它！

我正在运行Doxygen版本1.8.10。