Using Doxygen with C, do you comment the function prototype or the definition? Or both?

Question

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 1

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.

Answer 2

Quoted from my answer to this question: C/C++ Header file documentation:

I put documentation for the interface (parameters, return value, what the function does) in the interface file (.h), and the documentation for the implementation (how the function does) in the implementation file (.c, .cpp, .m). I write an overview of the class just before its declaration, so the reader has immediate basic information.

With Doxygen, this means that documentation describing overview, parameters and return values (\brief, \param, \return) are used for documenting function prototype and inline documentation (\details) is used for documenting function body (you can also refer to my answer to that question: How to be able to extract comments from inside a function in doxygen?)