From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19964 invoked by alias); 26 Aug 2011 08:04:38 -0000 Received: (qmail 19954 invoked by uid 22791); 26 Aug 2011 08:04:36 -0000 X-SWARE-Spam-Status: No, hits=-2.7 required=5.0 tests=AWL,BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,RCVD_IN_DNSWL_LOW X-Spam-Check-By: sourceware.org Received: from mail-gy0-f169.google.com (HELO mail-gy0-f169.google.com) (209.85.160.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 26 Aug 2011 08:04:22 +0000 Received: by gyg10 with SMTP id 10so2802570gyg.0 for ; Fri, 26 Aug 2011 01:04:21 -0700 (PDT) MIME-Version: 1.0 Received: by 10.236.187.104 with SMTP id x68mr4436250yhm.130.1314345861457; Fri, 26 Aug 2011 01:04:21 -0700 (PDT) Received: by 10.236.34.193 with HTTP; Fri, 26 Aug 2011 01:04:21 -0700 (PDT) In-Reply-To: <831uw9gzro.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> <831uw9gzro.fsf@gnu.org> Date: Fri, 26 Aug 2011 08:04: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/msg00476.txt.bz2 On Thu, Aug 25, 2011 at 10:35 AM, Eli Zaretskii wrote: >> Date: Thu, 25 Aug 2011 05:32:46 -0700 >> From: Matt Rice >> Cc: gdb-patches@sourceware.org >> >> 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: =A0#define A >> macro1.c:8: =A0#define B >> macro1.c:9: =A0bp1: >> macro1.c:10: =A0foo(); >> macro1.c:11: =A0#undef A >> macro1.c:12: =A0#undef B >> macro1.c:13: =A0#define B 1 >> macro1.c:14: =A0bp2: >> macro1.c:15: =A0foo(); >> macro1.c:16: =A0#define C >> macro1.c:17: =A0bp3: >> macro1.c:18: =A0foo(); 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 > include_trail=3D[('/home/ratmice/tests/macro1.h', 1), >> ('/home/ratmice/tests/macro1.c', 1)]> >> >> macro1.c:15 > include_trail=3D[('/home/ratmice/tests/macro1.h', 1), >> ('/home/ratmice/tests/macro1.c', 1)]> >> macro1.c:15 >> >> macro1.c:18 > include_trail=3D[('/home/ratmice/tests/macro1.h', 1), >> ('/home/ratmice/tests/macro1.c', 1)]> >> macro1.c:18 >> macro1.c:18 > > So far as expected. > >> >> +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. =A0When Symtab_and_line.macr= os() >> outputs all of the macros which were defined before the line, which >> are still in effect. > > Sorry, I don't follow. =A0Did you mean "B" instead of "C"? =A0What is the > problem you see here with "C"? =A0It is defined only once, on line 16, > and so is in effect on line 18. =A0I see no issues here. =A0What am I > missing? No, I mean "C". >> macro1.c:18: =A0foo(); C; return 0; So say we are stopped on this line, and have Symtab_and_line for it. the user wants to know `all the macros that are used at this source locatio= n' In this case the answer would be 'C', and my concern is that 'which are in effect' can be misconstrued. e.g. with the above line in isolation, is 'C' in effe= ct? how about the following. Returns all of the macros defined before the source line given by the @code{gdb.Symtab_and_line}'s @code{line} attribute which are in still 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.' > > Based on the example above (which I highly recommend to have in the > manual), I'd say "a list of macro objects with their values and > include trail". hrm, except what is above is the output of the string function, if you actually print the return value without converting to a string it prints something like (, ), But that is fine if you prefer it that way. >> >> +@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() =A0 =A0 =A0 =A0 =A0 =A0 =A0wsta= ndout(stdscr) > > This is marginal enough to have a special exception: > > =A0Returns @code{True} if the macro accepts an argument list. =A0A > =A0function-like macro that accepts an empty argument list also yields > =A0@code{True}. > ok, thanks.