Re: [patch][python] Add symbol, symbol table and frame block support to GDB API

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 03 Feb 2010 20:55:34 +0000
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: gdb-patches@sourceware.org
> 
> This is a multi-part message in MIME format.
> --------------050506000002080100010500
> Content-Type: text/plain; charset=ISO-8859-1
> Content-Transfer-Encoding: 7bit
> 
> On 02/02/2010 08:14 PM, Eli Zaretskii wrote:
> 
> >>>> +All of the name-scope contours of a program are represented as 'block'
> >>>
> >>> What are "contours"?  Is this a widespread enough terminology to be
> >>> understood without defining it first?  If not, I suggest to define it.
> >>
> >>
> >> I really agonized over the whole block description, as there is no (as
> >> far as I know) analogue to the GDB CLI for blocks.  It's revealing an
> >> API that GDB uses to manipulate blocks in a frame.  I could use some
> >> help making this more palatable enough to the consumer of the API,
> >> over trying to teach the user compiler/runtime semantics (which is not
> >> the purpose of the GDB manual).  What do you think?
> > 
> > How about if you tell what you want in the most technical way you
> > think about these issues, disregarding the fact that it's for GDB
> > users, and I will then rephrase it to be palatable to mere mortals?
> 
> 
> I've attached an updated patch.  What do you think?

It's good, thanks.  I have only a couple of comments:

> +@defivar Symbol is_argument
> +Is @code{True} if the symbol is an argument of a function.

I'd prefer to drop the "Is" part altogether, here and elsewhere.

> +@findex SYMBOL_LOC_ARG
> +@findex gdb.SYMBOL_LOC_ARG
> +@item SYMBOL_LOC_ARG
> +Value is an argument.

The comment in the source says:

  /* It's an argument; the value is at SYMBOL_VALUE offset in arglist.  */

Should we expand the above description by adding some text from the
comment?

> +@findex SYMBOL_LOC_REF_ARG
> +@findex gdb.SYMBOL_LOC_REF_ARG
> +@item SYMBOL_LOC_REF_ARG
> +Value address is an offset in arglist.

The comment in the code seems to be a continuation of the previous
comment (shown above).  Again, perhaps we should say more.  Can you or
someone else explain what these constants mean, i.e. say a bit more
than the comment says?