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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 01 Feb 2010 13:42:13 +0000
> From: Phil Muldoon <pmuldoon@redhat.com>
> 
> This patch adds symbol, symbol table and block support to the Python GDB API.  It also reconstitutes several functions missing from py-frame, and adds the glue back into python.c to make these code segments work together.  This is for the most part a merge of the code that has existed in the archer repository for sometime.
> 
> OK?

Thanks.  I have a few comments regarding the doco part.

> +* Frames In Python::            Accessing inferior stack frames from Python.
> +* Blocks In Python::            Accessing frame blocks from Python.
> +* Symbols In Python::           Python representation of Symbols.
> +* Symbol Tables In Python::     Symbol table representation in Python.
>  * Lazy Strings In Python::      Python representation of lazy strings.

I would prefer a consistent phrasing here: "Python representation of FOO".

> +@defmethod Frame block
> +Returns the frame's code block.  (@pxref{Blocks In Python}).

Please use "@xref{Blocks In Python}." here (without the parens).
@pxref is for references in the middle or end of a sentence.
Stand-alone cross-references should use @xref.

You have a few more of these.

> +@defmethod Frame select
> +Set this frame to be the user's selected frame.

I got confused by "user's selected frame" in this description.  If you
meant the "selected frame" in the sense we use that in the node
"Stack", then I suggest to drop the "user's" part and add a
cross-reference to the node "Stack" where this term is explained.

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

Also, we don't use single quotes in Texinfo, as in 'block'.  If you
meant to make it stand out, I suggest @dfn{block objects} instead.  If
you meant to quote it, please use double quotes, as in ``block''.

> +                                       Each @code{gdb.Block} object
> +has to be sourced, and parented from a @code{gdb.Frame} object.

I don't understand what it means ``sourced and parented from''.

> +                              This can be summarized as: each block
> +represents one name scope; each lexical context has its own block.

Are you sure people without solid background in compilers will
understand this?

> +@findex gdb.block_for_pc pc

findex entries should not include arguments, just the name of the
function.

> +@defun block_for_pc pc
> +Return the @code{gdb.Block} containing the given @code{pc} value.  If the
                                                    ^^^^^^^^^
Arguments should have a @var markup, not @code.

> +@defivar Block superblock
> +This attribute holds the superblock containing this block represented as a

Isn't it better to say

  This attribute holds the block containing this block

?  After all, the value of the superblock attribute is just another
block, right?

> +@value{GDBN} represents the name of every variable, function and type
> +as a symbol (@pxref{Symbols, ,Examining the Symbol Table}).

I think, from the GDB user POV, a name of a variable, function, and
type is just a string, not a symbol.

> +@findex gdb.lookup_symbol name [block] [domain]

Arguments in @findex again.

> +@defivar Symbol print_name
> +The name of the symbol in a form suitable for output.  This is either
> +name or linkage_name, depending on whether the user asked @value{GDBN}

Please give "name" and "linkage_name" the @code markup here, since
they are names of attributes.

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

"Returns"? maybe you meant "holds"?  This is an attribute, not a
method, right?

> +@item SYMBOL_VAR_DOMAIN
> +This domain contains variables, function names, typedef names and enum
> +type values.

Isn't this description too C-centric?  What about other languages?

> +@item SYMBOL_STRUCT_DOMAIN
> +This domain holds struct, union and enum type names.
> +@findex SYMBOL_LABEL_DOMAIN
> +@findex gdb.SYMBOL_LABEL_DOMAIN
> +@item SYMBOL_LABEL_DOMAIN
> +This domain contains names of labels (for gotos).

Same here.

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

I couldn't understand what this means.

> +               Access to the @code{gdb.Symtab_and_line} object for
> +each frame is returned from the @code{find_sal} method in
> +@code{gdb.Frame} object (@pxref{Frames In Python}).

Something is wrong in this sentence ("Access to ... object ... is
returned from ..." -- how can access be returned from somewhere?).

> +For more information on @value{GDBN}'s symbol table management
> +@xref{Symbols, ,Examining the Symbol Table}.
   ^^^^^
You want "see @ref" here, since "@xref" produces a capitalized "See",
which will look wrong in the middle of a sentence.

> +
> +A @code{gdb.Symtab_and_line} object has the following attributes:
> +
> +@table @code
> +@defivar Symtab_and_line symtab
> +The symbol table object (@code{gdb.Symtab}) for this frame.
> +This attribute is not writable.
> +@end defivar
> +
> +@defivar Symtab_and_line pc
> +Indicates the current program counter address.  This attribute is not
> +writable.
> +@end defivar
> +
> +@defivar Symtab_and_line line
> +Indicates the current line number information for this object.

What is the ``current line information''?  Do you mean line number?
If not, what kind of object is it?

> +@defivar Symtab objfile
> +The symbol table's backing object file. @xref{Objfiles In Python}.
                                         ^^
Two spaces, please.

> +@defmethod Symtab fullname
> +Return the symbol table's full source filename.

"Full" as in "absolute file name" or something else?

Do we need a NEWS entry for this?