This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]