Using Doxygen with C, do you comment the function prototype or the definition? Or both?
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?
Answer
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.