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

Stan Shebs
2009-06-23T19:59:09Z

Tom Tromey wrote:
>>>>>> "Joel" == Joel Brobecker <brobecker@adacore.com> writes:
>>>>>>
>
> Joel> Unfortunately, I don't think we really have a hard convention in GDB.
> Joel> For C, I also tend to prefer documenting the function next to the
> Joel> implementation. It's the only way to be consistent, since some functions
> Joel> do not have advance declarations.
>
> FWIW, I prefer to have documentation in the header for a module's
> public API, and next to the implementation for the private API.
> Consistency doesn't matter as much to me as being able to read a
> header file and get a grasp of how I would use a module; the private
> comments in the module can then describe the implementation.
>
I think that in many cases functions in a header don't get documentation
there because they are intended to be semi-private, and are only in a
header because of the rules of C and our own conventions. For such
functions it would at least be useful to have a line "semi-private,
don't assume you can use this for your own purposes".

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

Stan