This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Joe Buck <Joe dot Buck at synopsys dot COM>
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Cc: law at redhat dot com, gcc at gcc dot gnu dot org
- Date: Thu, 29 Jan 2004 12:34:31 -0800
- Subject: Re: "Documentation by paper"
- References: <10401291907.AA16043@vlsi1.ultra.nyu.edu>
On Thu, Jan 29, 2004 at 02:07:03PM -0500, Richard Kenner wrote:
> Conceptually, an API should be usable without looking at the
> implementation.
>
> Most certainly!
>
> In Ada, the specification and implementation are always in different files,
> so that can actually be enforced.
>
> You can that in C too, of course, by putting the specification into the .h
> file and the implementation into the .c file, but the convention has been to
> document the function's parameters in the .c file rather than .h.
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.