我正在使用Doxygen处理一些嵌入式C源代码。对于一个.c/.h文件对，您是将Doxygen的注释放在函数原型（.h文件）上还是放在函数定义（.c文件）上，或者两个位置都重复添加注释？
我遇到了一个问题，即当我只在一个地方记录文档而不在另一个地方时，Doxygen会警告缺少注释; 这是否是预期行为，还是我的Doxygen出了问题？
5个回答
21
对于公共API，我会在声明中进行文档记录，因为这是用户查看的第一个地方，如果不使用doxygen输出。
我从未在一个地方记录文档遇到过问题，但我使用的是C++，对于C来说可能有所不同，尽管我怀疑。
[编辑] 不要重复写两次。永远不要。源代码文档也要遵循DRY原则，特别是涉及复制和粘贴的举动。
然而，您可以指定是否希望未记录元素的警告. 尽管这样的警告在理论上看起来不错，但我的经验是它们很快变得更加累赘而不是有用。通常不需要记录所有函数（存在冗余文档，甚至会妨碍文档撰写，特别是当文档太多时）；良好的文档需要有知识渊博的人花时间编写。鉴于此，这些警告是不必要的。
如果您没有编写良好文档的资源（资金、时间或其他），那么这些警告也无济于事。
- gimpf
10
以下是我对这个问题的回答摘录：C/C++头文件文档化:
我将接口（参数、返回值和函数作用）的文档放在接口文件（.h）中，将实现（函数如何工作）的文档放在实现文件（.c、.cpp、.m）中。我会在类的声明之前写一个概述，以便读者可以快速获取基本信息。
使用Doxygen时，这意味着用于描述概述、参数和返回值(\brief, \param, \return)的文档应该用于文档化函数原型，而内联文档(\details)则用于文档化函数体(也可以参考我的另一篇回答：如何能从Doxygen中提取函数内部的注释？)。
- mouviciel
1
mouviciel - 我尝试了一些实验，使用 \brief（或设置使其假定第一句话是简要文本）在 .h 文件中，并在 .cpp 文件中使用 \details。在 doxygen 输出中呈现的内容包括“... /details ...”，就好像 /details 没有被处理为 doxygen 命令一样。您能否提供一个具有最小文档的 .h 示例和一个具有详细信息的 .cpp，就像您上面建议的那样？提前致谢。 - Chris Markle
4
我经常使用Doxygen来对针对嵌入式系统的C代码进行文档编写。我尽量在一个地方为每个单独的对象编写文档，因为重复会导致以后的混淆。Doxygen可以合并一些文档，因此原则上可以在.h文件中记录公共API，并在.c文件中添加关于其实际工作方式的说明。我自己试着不这样做。
如果将文档从一个地方移动到另一个地方会改变警告的数量，那么这可能表明声明和定义之间有一些微妙的不同之处。例如，代码是否可以用-Wall -Wextra干净地编译？是否有宏在一个地方改变了代码但在另一个地方没有？当然，Doxygen的解析器不是完整的语言解析器，也可能出现混淆。
如果将文档从一个地方移动到另一个地方会改变警告的数量，那么这可能表明声明和定义之间有一些微妙的不同之处。例如，代码是否可以用-Wall -Wextra干净地编译？是否有宏在一个地方改变了代码但在另一个地方没有？当然，Doxygen的解析器不是完整的语言解析器，也可能出现混淆。
- RBerteig
2
我们只注释函数定义，但是在C++中使用它。
在两个地方都写会浪费时间。
至于警告，如果您的文档看起来不错，也许忽略这样的警告是一个好方法。
- Matthieu
1
我曾经问过自己同样的问题，令人惊喜的是，当浏览生成的HTML文档时，Doxygen实际上包含了与.c文件中相同的内联文档。因此，您不必重复您的内联文档，Doxygen足够智能以在两个位置都包含它！
我正在运行版本为Doxygen 1.8.10。
- jigglypuff
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接