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

[Stan Shebs <stan@codesourcery.com>]

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