This is the mail archive of the
mailing list for the GCC project.
Re: "Documentation by paper"
> 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).