Headers:
Easier to read the comments since there is less other "noise" when looking at the files.
Source:
Then you have the actual functions available for reading while looking at the comments.
We just use all global functions commented in headers and local functions commented in source. If you want you can also include the copydoc command to insert the documentation in multiple places without having to write it several times ( better for maintenance )
You could however also get the results copied over to different file documentation with a simple command. E.g. :-
My file1.h
/**
* \brief Short about function
*
* More about function
*/
WORD my_fync1(BYTE*);
MY file1.c
/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}
Now you get the same documentation on both functions.
This gives you less noise in the code files at the same time you get the documentation written in one place presented in several places in the final output.
