使用Doxygen与C，你评论功能原型或定义？或两者？ [英] Using Doxygen with C, do you comment the function prototype or the definition? Or both?
问题描述
我有一个问题，当我在一个地方而不是另一个地方记录时，Doxygen正在警告错误的注释;这是预期的，还是我的Doxygen搞砸了？
对于公共API，我在声明中记录，因为这是如果没有使用doxygen输出，用户通常会先看看。
我从来没有只在一个地方记录文档的问题，但是我用C ++使用它;可能与C不同，虽然我怀疑它。
永远不要写两次。决不。源代码文档也遵循DRY，特别是关于这种复制和粘贴变换。[/ edit]
但是，您可以指定是否要对未记录元素的警告。虽然这样的警告在理论上看起来不错，但我的经验是，他们很快就是一个负担而不是帮助。记录所有功能通常不是要走的路（有这样的事情是冗余的文档，甚至阻碍文档，尤其是文档太多）;良好的文件需要知识渊博的人花费时间。鉴于这些警告是不必要的。
如果您没有资源编写良好的文档（金钱，时间，任何...），比那些警告赢得
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?
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?
For public APIs I document at the declaration, as this is where the user usually looks first if not using the doxygen output.
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屋！
