Re: FYI: minsyms documentation

[Stan Shebs <stanshebs@earthlink.net>]

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