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)

Answer 1

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?)

Answer 2

I often use Doxygen with C targeting embedded systems. I try to write documentation for any single object in one place only, because duplication will result in confusion later. Doxygen does some amount of merging of the docs, so in principle it is possible to document the public API in the .h file, and to have some notes on how it actually works sprinkled in the .c file. I've tried not to do that myself.

If moving the docs from one place to the other changes the amount of warnings it produces, that may be a hint that there may be something subtly different between the declaration and definition. Does the code compile clean with -Wall -Wextra for example? Are there macros that mutate the code in one place and not the other? Of course, Doxygen's parser is not a full language parser, and it is possible to get it confused as well.

Answer 3

I've asked myself the same question and was pleasantly surprised to see that Doxygen actually includes the same in-line documentation that is in the .c file in the corresponding .h file when browsing the generated html documentation. Hence you don't have to repeat your in-line documentation, and Doxygen is smart enough to include it in both places!

I'm running version Doxygen version 1.8.10.

Answer 4

We comment only the function definitions, but we use it with C++.
Write it at both places is wasting time. About the warning, if your documentation looks good, maybe it's a good way to ignore such warnings.

Answer 5

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.