[RFC] Stop putting function comments in foo.h

[DJ Delorie]

Pedro Alves <palves@redhat.com> writes:
> 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.  :-)

Speaking from the "someone who uses the API but doesn't understand the
source tree" point of view, it's usually a lot easier to discover an API
through the header files, and that's where I expect to find some
documentation about the API.

The only time that documentation-in-source works is when there's a
strict one-to-one mapping of headers to sources, else finding the
documentation becomes yet another task to hurdle.

Also, I've yet to find a doxygen doc set that adds any value over just
commenting the headers.

Also, IMHO there should be *two* sets of in-source docs: the headers
should have comments suitable for users of each API, and the source
should have comments relevent to those editing the implementation.