Re: FYI: minsyms documentation

[Michael Eager <eager at eagerm dot com>]

On 12/21/2011 06: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.

I realize that I'm late to this discussion, but I dislike this approach
and think that it will make maintaining GDB more difficult and makes
using and maintaining the documentation more difficult.

It requires looking in two places, the .c and the .h at the same
time.  When I'm debugging something, the .c is in the debugger window
and if there are any useful comments I see them.  This change requires
me to open the .h in a different editor window and search for the
function name.  Most of the time I'm not going to do this, since almost
all the time, the comments don't say very much.  This means that when
there is a comment which might explain what to me is an unexpected
behavior, I'm likely to see it only much later, if at all, when it
occurs to me that there might be something in the .h file which is
relevant.

Best practice, comments are best kept close to the code that they
refer to.  Maintainers are likely to update comments if they are
next to the modified code, and much less likely if the comments are
somewhere else.  It doesn't matter if that somewhere else is in a .h
file, or in the .texi files, or in some other area.  There are actually
decades of experimental evidence in favor of keeping detailed comments
close to the relevant code, rather than removing them to a different
location.

It would be nice to see GDB documentation improve and documenting
the APIs would be great.  I see this as providing high level concept
documentation which explains how a particular API works, why it exists,
and how it interacts with other APIs.  Minimal documentation of each
function, without context, is not this.  As far as I can tell, there
minsyms.h contains one very short paragraph which provides a bit of
context and there is no general overview.

To use an analogy, this is like giving you the description of a
spark plug, a fuel pump, and a crankshaft, and expecting you to figure
out how these interact to make a car engine turn.

--
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077