[RFC] Stop putting function comments in foo.h

[Pedro Alves]

On 03/15/2014 07:45 PM, Doug Evans wrote:
> 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?

IMO, yes.  And IMO doxygen here is a red herring.
I actually don't see myself looking at doxygen docs
much.  Doxygen is supposed to be an aid, there should be no
requirement to build the doxygen docs to be able to understand
gdb's sources, right?

IMO, a module's API documentation should be in its header file, as
that's where the module's "public" contract is defined.
Needing to peek at the module's implementation feels wrong to me.
If the function's documentation isn't clear without looking
at the function's body, something is already wrong with
the comment.

> 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.

Whenever I look at a header file that doesn't document its
functions' interfaces (and often doesn't even list the
parameter names), I get depressed and disappointed.  I'm
wondering if it's just me.  :-)

-- 
Pedro Alves