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: FYI: minsyms documentation


On 12/22/11 12:13 PM, Tom Tromey wrote:
"Stan" == Stan Shebs<stanshebs@earthlink.net> writes:
Stan> On 12/21/11 6:34 PM, Tom Tromey wrote:
I am checking this in on the trunk.

Today I decided to try to document the minsyms API more or less the way
I would like APIs to be documented in general.  This patch implements
that; it move documentation from function definitions to minsyms.h, adds
an introductory comment about minsyms there as well, and it rearranges
the header into a more logical order.
Stan> I'm not liking this idea very much I'm afraid.

Ok.

Do you mean you want me to back out the patch?
Let me know.

We don't need to be that hasty. :-) I'd like to see more thoughts and reactions; if everybody else likes it, I won't stand in the way of progress!



Stan> Second, this is potentially a very large change to the sources, but if Stan> it's incremental, then we get into a confusing situation where some Stan> files are changed, others are not, and some headers are half-changed Stan> because they service multiple source files.

This is the present situation.

True, and certainly we should provide some sort of guidance on the point.


One way to look at it is if we assume that the transition to C++ occurs at some point, what happens to current function head comments? Do they tend to stay put, as explanation of a method's implementation, or do they tend to migrate to class definitions in headers? Perhaps method implementations won't often need head comment blocks at all, as the interface is documented in headers, and anything interesting in the implementation is described with inline comments as is is now.

Stan


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