Re: FYI: minsyms documentation

[Tom Tromey <tromey at redhat dot com>]

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

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.

Tom> My view is that gdbint.texinfo should eventually hold a high-level
Tom> overview of the different modules in GDB, but that each individual
Tom> module should be documented in the relevant header files.  My reason for
Tom> this is just that it is simpler to update documentation when it is in
Tom> the form of comments.  I think gdbint.texinfo should also hold
Tom> documentation on our procedures, coding styles, and other things that
Tom> are not directly related to some piece of code.

Stan> Isn't that generally our working assumption now?

My working assumption is that gdbint.texinfo is barely maintained at
all.

Tom