From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4626 invoked by alias); 1 Feb 2010 20:54:08 -0000 Received: (qmail 4614 invoked by uid 22791); 1 Feb 2010 20:54:07 -0000 X-SWARE-Spam-Status: No, hits=0.5 required=5.0 tests=AWL,BAYES_50,KAM_STOCKGEN,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout21.012.net.il (HELO mtaout21.012.net.il) (80.179.55.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 01 Feb 2010 20:53:58 +0000 Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0KX600000KI62B00@a-mtaout21.012.net.il> for gdb-patches@sourceware.org; Mon, 01 Feb 2010 22:53:55 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.70.67.249]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KX600KWNKPU6YA0@a-mtaout21.012.net.il>; Mon, 01 Feb 2010 22:53:55 +0200 (IST) Date: Mon, 01 Feb 2010 20:54:00 -0000 From: Eli Zaretskii Subject: Re: [patch][python] Add symbol, symbol table and frame block support to GDB API In-reply-to: <4B66DA35.7080701@redhat.com> To: Phil Muldoon Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83sk9khe3b.fsf@gnu.org> References: <4B66DA35.7080701@redhat.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-02/txt/msg00030.txt.bz2 > Date: Mon, 01 Feb 2010 13:42:13 +0000 > From: Phil Muldoon > > 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?