From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3806 invoked by alias); 24 Aug 2011 20:10:30 -0000 Received: (qmail 3717 invoked by uid 22791); 24 Aug 2011 20:10:09 -0000 X-SWARE-Spam-Status: No, hits=-0.8 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL,TW_BJ,TW_RG X-Spam-Check-By: sourceware.org Received: from mtaout22.012.net.il (HELO mtaout22.012.net.il) (80.179.55.172) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 24 Aug 2011 20:09:53 +0000 Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0LQG00I007ZBK600@a-mtaout22.012.net.il> for gdb-patches@sourceware.org; Wed, 24 Aug 2011 23:09:29 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.126.219.41]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LQG00H487ZSU4Q0@a-mtaout22.012.net.il>; Wed, 24 Aug 2011 23:09:29 +0300 (IDT) Date: Wed, 24 Aug 2011 20:10:00 -0000 From: Eli Zaretskii Subject: Re: [PATCH 6/7] [python] API for macros: Add docs. In-reply-to: <1314198654-9008-7-git-send-email-ratmice@gmail.com> To: matt rice Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83k4a2h8qr.fsf@gnu.org> References: <1314198654-9008-1-git-send-email-ratmice@gmail.com> <1314198654-9008-7-git-send-email-ratmice@gmail.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: 2011-08/txt/msg00460.txt.bz2 > From: matt rice > Cc: matt rice > Date: Wed, 24 Aug 2011 08:10:53 -0700 > > --- a/gdb/NEWS > +++ b/gdb/NEWS > @@ -38,6 +38,13 @@ > > ** Symbols now provide the "type" attribute, the type of the symbol. > > + ** Objfiles now provide a "symtabs" method. > + > + ** The Macro object is now available for representing preprocessor macros. > + The following objects now have methods for obtaining macro objects. > + - Symtab_and_line now has a "macro_named" method > + - Symtab now has a "macros" method. This part is okay, but please add a reference to the section in the manual where these are described. > +@defmethod Symtab_and_line macro_named @r{[}name@r{]} > +Returns a @code{gdb.Macro} object, for the macro > +with the given name. > +@end defmethod This should say what happens if "name" is omitted. It's optional, right? > +@defmethod Symtab_and_line macros > +Returns all of the macros which are defined and not undefined or redefined, "not redefined"? what exactly does this mean, and how can GDB distinguish between something that is defined and something that is defined and then redefined? > +prior to the the @code{gdb.Symtab_and_line}'s line attribute. > +Thus, all the macros which would be validly usable at that line. I would rephrase: Returns all of the macros which are in effect for the source line given by the @code{gdb.Symtab_and_line}'s @code{line} attribute. > +@defmethod Symtab macros > +Return all of the macros contained in the symbol table. > +@end defmethod Return what, exactly? only their names? something else? > +@code{gdb.Macro} class. For obtaining a @code{gdb.Macro} object see > +@xref{Symbol Tables In Python}. You want "see @ref". @xref produces a capitalized "Note:", which will look as bad English; use @xref only at the beginning of a sentence. > +@code{gdb.Macro} methods may produce a lazily created python copy from ^^^^^^ "Python". > +gdb's internal representation possibly returning different copies ^^^ @value{GDBN} > +The @code{gdb.Macro} class should be considered an abstract class, > +instances possibly being of different types. Thus, you should always call > +its functions directly from an instance, And never reference a method ^^^ "and" > +@defmethod Macro argv > +Returns a list of the macros arguments if the macro is function like. > +If the macro is not function like, returns @code{None} Returns the argument list of the macro, or @code{None} if the macro does not accept arguments. > +@defmethod Macro definition > +Returns a string containing the definition of the macro. > +@end defmethod Returns a string containing the macro body. > +@defmethod Macro include_trail > +Returns a list of tuples containing the filenames, and line numbers ^ This comma is redundant. > +of header and source files that correspond to the include directives, > +and location of definition. The list is sorted starting with the place > +of definition, and ending with the first include directive. > +@end defmethod An example of this list of tuples would go a long way towards making this description more clear. > +@defmethod Macro is_function_like > +Returns @code{True} If the macro is function like. > +@end defmethod Returns @code{True} if the macro accepts arguments. > +@defmethod Macro is_valid > +Returns @code{True} if the macro is valid. And presumably False otherwise. > +All other @code{gdb.Macro} methods will throw an exception if the object is What exception? Is that important to document? > +invalid at the time the method is called. > +A macro which becomes invalid will never be valid again > +without looking up the macro again to create a new @code{gdb.Macro} > +object. > +@end defmethod Please tell here what does it mean for a macro to be "valid". Also, how to "look up the macro again". Finally, it sounds like this method should be the first one documented, as it is the only one that is always usable. Thanks.