Where to document functions in C or C++?

Question

I have a C program with multiple files, so I have, for example, stuff.c which implements a few functions, and stuff.h with the function prototypes.

How should I go about documenting the functions in comments?

Should I have all the docs in the header file, all the docs in the .c file, or duplicate the docs for both? I like the latter approach, but then I run into problems where I'll update the docs on one of them and not the other (usually the one where I make the first modification, i.e. if I modify the header file first, then its comments will reflect that, but if I update the implementation, only those comments will change).

This question and its answers also apply to C++ code — see also Where should I put documentation comments?

Answer 1

• Put the information that people using the functions need to know in the header.

• Put the information that maintainers of the functions need to know in the source code.