From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 1785 invoked by alias); 25 Aug 2011 12:33:03 -0000 Received: (qmail 1746 invoked by uid 22791); 25 Aug 2011 12:33:02 -0000 X-SWARE-Spam-Status: No, hits=-2.6 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW,TW_BJ X-Spam-Check-By: sourceware.org Received: from mail-yx0-f169.google.com (HELO mail-yx0-f169.google.com) (209.85.213.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 25 Aug 2011 12:32:47 +0000 Received: by yxn35 with SMTP id 35so1818821yxn.0 for ; Thu, 25 Aug 2011 05:32:46 -0700 (PDT) MIME-Version: 1.0 Received: by 10.236.9.101 with SMTP id 65mr40519188yhs.11.1314275566849; Thu, 25 Aug 2011 05:32:46 -0700 (PDT) Received: by 10.236.34.193 with HTTP; Thu, 25 Aug 2011 05:32:46 -0700 (PDT) In-Reply-To: <83k4a2h8qr.fsf@gnu.org> References: <1314198654-9008-1-git-send-email-ratmice@gmail.com> <1314198654-9008-7-git-send-email-ratmice@gmail.com> <83k4a2h8qr.fsf@gnu.org> Date: Thu, 25 Aug 2011 12:33:00 -0000 Message-ID: Subject: Re: [PATCH 6/7] [python] API for macros: Add docs. From: Matt Rice To: Eli Zaretskii Cc: gdb-patches@sourceware.org Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable 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/msg00463.txt.bz2 On Wed, Aug 24, 2011 at 1:09 PM, Eli Zaretskii wrote: >> 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 @@ >> >> =A0 =A0** Symbols now provide the "type" attribute, the type of the symb= ol. >> >> + =A0** Objfiles now provide a "symtabs" method. >> + >> + =A0** The Macro object is now available for representing preprocessor = macros. >> + =A0 =A0 The following objects now have methods for obtaining macro obj= ects. >> + =A0 =A0 - Symtab_and_line now has a "macro_named" method >> + =A0 =A0 - 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. ok, will send a new patch after the we get the below stuff figured out. >> +@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. =A0It's optional, > right? Nope, removed the []'s >> +@defmethod Symtab_and_line macros >> +Returns all of the macros which are defined and not undefined or redefi= ned, > > "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? the symtab_and_line method distinguishes something that is defined and then redefined by using the last defined version of the macro (in this case) here's an example and later a question macro1.h:1:#define AMACRO macro1.c:1:#include "macro1.h" macro1.c:2: macro1.c:3:void foo() {}; macro1.c:4: macro1.c:5:int main() macro1.c:6:{ macro1.c:7: #define A macro1.c:8: #define B macro1.c:9: bp1: macro1.c:10: foo(); macro1.c:11: #undef A macro1.c:12: #undef B macro1.c:13: #define B 1 macro1.c:14: bp2: macro1.c:15: foo(); macro1.c:16: #define C macro1.c:17: bp3: macro1.c:18: foo(); C; return 0; macro1.c:19:} lets say we break at bp1 bp2 and bp3 labels and output the Symtab_and_line.macros(), and get rid of all of the compiler generated macros. macro1.c:10 macro1.c:10 macro1.c:10 macro1.c:15 macro1.c:15 macro1.c:18 macro1.c:18 macro1.c:18 >> +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: > > =A0Returns all of the macros which are in effect for the source line > =A0given by the @code{gdb.Symtab_and_line}'s @code{line} attribute. The problem I was trying to avoid (and which made my documentation for this method admittedly crappy), is that your rephrased definition seems to be plausible for the case when the user wants (C) in the macro1.c:18 case, e.g. the macros which are used ON the line. When Symtab_and_line.macros() outputs all of the macros which were defined before the line, which are still in effect. >> +@defmethod Symtab macros >> +Return all of the macros contained in the symbol table. >> +@end defmethod > > Return what, exactly? only their names? something else? i'll try 'Return a list of macro objects for all of the macros contained in the symbol table.' >> +@defmethod Macro is_function_like >> +Returns @code{True} If the macro is function like. >> +@end defmethod > > =A0Returns @code{True} if the macro accepts arguments. I understand the intent to make this documentation not so self-recursive I tried to think of a way too, but the problem with this is the rare function-like macro which accepts no arguments, e.g. /usr/include/curses.h:#define standout() wstandout(stdscr)