Re: "Documentation by paper"

[Andrew Sutton <asutton at cs dot kent dot edu>]

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

just a comment... no pun intended. commenting header files is great, but if 
you're using a documentation extractor then you probably don't need to. 
besides, in an active build environment, changing the documentation in a 
header file can be a real pain if there are dependencies on the header file.

just a thought... why rely on header files for api documentation anyway. i 
mean, if i need to remind myself of the parameters to open(), i don't look at 
unistd.h, i look at the man page. it should be no different for internal 
api's either (not man pages per se, but other documentation).

andrew sutton
asutton@cs.kent.edu