This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [commit] cleanup stale exec.{h|c} xfer_memory comments.
>>>>> "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