Re: [commit] cleanup stale exec.{h|c} xfer_memory comments.

[Tom Tromey <tromey at redhat dot com>]

>>>>> "Stan" == Stan Shebs <stan@codesourcery.com> writes:

Stan> I think that in many cases functions in a header don't get
Stan> documentation there because they are intended to be semi-private, and
Stan> are only in a header because of the rules of C and our own
Stan> conventions.  For such functions it would at least be useful to have a
Stan> line "semi-private, don't assume you can use this for your own
Stan> purposes".

Yeah.  My ideal in these cases is to have a second header which is
private to the implementation.

Stan> Should we maybe introduce a coding rule requiring at least a brief
Stan> API/usage comment about each function declaration in a header? Perhaps
Stan> all the semi-private functions can be separated into a block with a
Stan> comment that applies to the lot of them.

It would be fine by me, for public APIs.  For existing messy headers,
I don't care so much (unless someone wants to do some big cleanups on
them), but I would like it if new headers were to be written to a
Blandyesque standard.

Tom