[RFC] Stop putting function comments in foo.h

[Ricard Wanderlof]

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

One solution would be to simply duplicate the documentation in both the .c 
and .h files. Sure, it's duplicated text, and there's always the 
possibility that they'll get out of sync with each other, but at least 
we're putting the burdon on whoever is writing the code, not whoever is 
reading it, which makes sense since the code will be read many more times 
than it is (re)written.

/Ricard
-- 
Ricard Wolf Wanderlöf                           ricardw(at)axis.com
Axis Communications AB, Lund, Sweden            www.axis.com
Phone +46 46 272 2016                           Fax +46 46 13 61 30