使用Doxygen的为C，你评论的函数原型或定义吗？或两者？ [英] Using Doxygen with C, do you comment the function prototype or the definition? Or both?

问题描述

我使用Doxygen的一些嵌入式C源代码。给定一个.C / h文件对，你把函数原型Doxygen的意见（h文件）或函数定义（.c文件），或者你复制他们在这两个地方？

I'm using Doxygen with some embedded C source. Given a .c/.h file pair, do you put Doxygen comments on the function prototype (.h file) or the function definition (.c file), or do you duplicate them in both places?

我在其中的Doxygen警告有关丢失的意见时，我在一个地方记录而不是其他问题;这种预期，或者是我的Doxygen搞砸了？

I'm having a problem in which Doxygen is warning about missing comments when I document in one place but not the other; is this expected, or is my Doxygen screwed up?

推荐答案

有关公共API文档我的声明，因为这是用户平时看起来第一，如果不使用doxygen的输出。

For public APIs I document at the declaration, as this is where the user usually looks first if not using the doxygen output.

我从来没有只仅在一个地方记录的问题，但我使用C ++使用它;可以用C不同，虽然我很怀疑。

I never had problems with only documenting on one place only, but I used it with C++; could be different with C, although I doubt it.

从来没有把它写两次。决不。在源文件如下干，过，特别是关于这种复制和粘贴变态。[/编辑]

[edit] Never write it twice. Never. In-Source documentation follows DRY, too, especially concerning such copy-and-paste perversions.[/edit]

不过，您可以指定是否要对无证元素警告。虽然这种警告在理论上看起来不错，我的经验是，他们很快就更多的不是帮助的负担。通常记录所有的功能是不是要（有这样的事情是多余文件，甚至阻碍文档，尤其是过多的文件）的方式;良好的文档需要一个懂行的人花时间与它。鉴于此，这些警告是不必要的。

However, you can specify whether you want warnings for undocumented elements. Although such warnings look nice in theory, my experience is that they quickly are more of a burden than a help. Documenting all functions usually is not the way to go (there is such a thing is redundant documentation, or even hindering documentation, and especially too much documentation); good documentation needs a knowledgeable person spending time with it. Given that, those warnings are unnecessary.

如果你没有足够的资源用于编写好的文档（金钱，时间，无论...），比这些警告将没有帮助。

And if you do not have the resources for writing good documentation (money, time, whatever...), than those warnings won't help either.

这篇关于使用Doxygen的为C，你评论的函数原型或定义吗？或两者？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！