Re: [RFC] Stop putting function comments in foo.h

[Gerhard Gappmeier <gerhard dot gappmeier at ascolab dot com>]

On Saturday, March 15, 2014 12:45:41 PM Doug Evans wrote:
> Hi.
> 
> I'd like to start a discussion.
> With doxygen is there still as much value to putting function comments
> in foo.h instead of foo.c?
> 
> I ask because every time I find a "See foo.h." comment I get depressed
> and disappointed.  They're just getting in my way, and I'm wondering
> if it's just me.
It's not just you ;-)

Hi had this discussion several times inside my company.
IMO the only valid reason for having the doxygen comments in the header file 
is when you are doing binary distributions with header files and libraries.
This is not the case for Open Source.

If code is distributed it makes more sense to have the comments in the source 
file. Here you need the comments as developer when debugging through the code, 
changing it, or just reviewing it. It annoys me to switch to the header file 
to see what a function is doing. Another advantage of doing so is that the 
header file stays clean if you want to get a quick overview of what functions 
are available.

But that's my opinion and I'm sure other people will have other opinions ;-)