Re: "Documentation by paper"

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

    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.

Sorry I wasn't clear: I certainly agree with that, but I don't think it's
realistic to get that changed given the pervasiveness of the opposing view.

What can be done as a compromise, and what I try to do, is to duplicate
all the information in front of a function at its declaration in the
header file. That has that effect, but is more of a maintenance burden
(though slight, due to cut-and-paste).