This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [patch][python] Add symbol, symbol table and frame block support to GDB API
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Phil Muldoon <pmuldoon at redhat dot com>
- Cc: gdb-patches at sourceware dot org
- Date: Mon, 01 Feb 2010 22:54:00 +0200
- Subject: Re: [patch][python] Add symbol, symbol table and frame block support to GDB API
- References: <4B66DA35.7080701@redhat.com>
- Reply-to: Eli Zaretskii <eliz at gnu dot 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?