我正在使用带有一些嵌入式 C 源的 Doxygen。给定一个 .c/.h 文件对，你是把 Doxygen 注释放在函数原型（.h 文件）还是函数定义（.c 文件）上，还是在两个地方都复制它们？
我有一个问题，当我在一个地方而不是另一个地方记录时，Doxygen 会警告缺少评论；这是预期的，还是我的 Doxygen 搞砸了？
问问题
21970 次
5 回答
20
对于我在声明中记录的公共 API，因为如果不使用 doxygen 输出，这是用户通常首先查看的地方。
我从来没有遇到过只在一个地方记录的问题，但是我将它与 C++ 一起使用；尽管我对此表示怀疑，但 C 可能会有所不同。
[编辑] 永远不要写两次。绝不。源内文档也遵循 DRY，尤其是关于这种复制和粘贴的变态。[/edit]
但是，您可以指定是否需要未记录元素的警告。尽管这样的警告在理论上看起来不错，但我的经验是，它们很快就会成为负担而不是帮助。记录所有功能通常不是办法（有这样的事情是冗余文档，甚至妨碍文档，尤其是过多的文档）；好的文档需要一个知识渊博的人花时间处理它。鉴于此，这些警告是不必要的。
如果你没有编写好的文档的资源（金钱、时间等等……），那么这些警告也无济于事。
于 2009-08-13T13:49:26.087 回答
10
从我对这个问题的回答中引用：C/C++ 头文件文档：
我将接口的文档（参数、返回值、函数的作用）放在接口文件（.h）中，将实现的文档（函数如何工作）放在实现文件（.c、.cpp、.米）。我在声明之前写了一个类的概述，所以读者可以立即获得基本信息。
使用Doxygen ，这意味着描述概述、参数和返回值的文档（\brief, \param, \return）用于记录函数原型，而内联文档（能够从 doxygen 中的函数内部提取注释吗？）\details
于 2009-08-26T08:20:57.380 回答
4
I often use Doxygen with C targeting embedded systems. I try to write documentation for any single object in one place only, because duplication will result in confusion later. Doxygen does some amount of merging of the docs, so in principle it is possible to document the public API in the .h file, and to have some notes on how it actually works sprinkled in the .c file. I've tried not to do that myself.
If moving the docs from one place to the other changes the amount of warnings it produces, that may be a hint that there may be something subtly different between the declaration and definition. Does the code compile clean with -Wall -Wextra for example? Are there macros that mutate the code in one place and not the other? Of course, Doxygen's parser is not a full language parser, and it is possible to get it confused as well.
于 2009-08-13T17:42:35.720 回答
2
我们只注释函数定义，但我们在 C++ 中使用它。
在这两个地方都写是浪费时间。关于警告，如果您的文档看起来不错，也许这是忽略此类警告的好方法。
于 2009-08-13T13:53:20.130 回答
0
我问过自己同样的问题，并惊喜地发现 Doxygen 在浏览生成的 html 文档时实际上包含了与 .c 文件中相应 .h 文件中的 .c 文件相同的内联文档。因此，您不必重复您的内联文档，并且 Doxygen 足够聪明，可以将它包含在两个地方！
我正在运行版本 Doxygen 版本 1.8.10。
于 2015-08-26T02:24:15.297 回答