Re: "Documentation by paper"

[Robert Dewar <dewar at gnat dot com>]

Joe Buck wrote:

> This is a mistake, in my view.  It has always been the practice on the
> teams I work with that a header file is supposed to be self-contained,
> in the sense that a user of a module only needs to read the declarations
> and documentation in the header file to use any functions declared there.
> Wading into the source code is of course needed for debugging, but if
> studying the source code is needed to figure out restrictions on use of
> the function, that means that the header documentation is not adequate.

I strongly agree with this position. But a more general comment is that
clearly there are two very different schools of thought on C headers, so
what is important is to have a clear policy and be consistent throughout
gcc. A mixture of the two styles (document in header, document in
implementation file) is the worst of all worlds.