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

[Tom Tromey <tromey@redhat.com>]

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

There are several examples of this in gdb already.  Consider:
macro*.[ch], bcache.[ch], dictionary.[ch], addrmap.[ch].

These are all exemplary code, which I think is not coincidental...  it
requires more work to write the code this way, but that forces one to
consciously consider the API.

Tom