Re: [PATCH 6/7] [python] API for macros: Add docs.

[Matt Rice <ratmice at gmail dot com>]

On Thu, Aug 25, 2011 at 10:35 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu, 25 Aug 2011 05:32:46 -0700
>> From: Matt Rice <ratmice@gmail.com>
>> 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: ?#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 <gdb.Macro B include_trail=[('/home/ratmice/tests/macro1.c', 8)]>
>> macro1.c:10 <gdb.Macro A include_trail=[('/home/ratmice/tests/macro1.c', 7)]>
>> macro1.c:10 <gdb.Macro AMACRO
>> include_trail=[('/home/ratmice/tests/macro1.h', 1),
>> ('/home/ratmice/tests/macro1.c', 1)]>
>>
>> macro1.c:15 <gdb.Macro AMACRO
>> include_trail=[('/home/ratmice/tests/macro1.h', 1),
>> ('/home/ratmice/tests/macro1.c', 1)]>
>> macro1.c:15 <gdb.Macro B=1 include_trail=[('/home/ratmice/tests/macro1.c', 13)]>
>>
>> macro1.c:18 <gdb.Macro AMACRO
>> include_trail=[('/home/ratmice/tests/macro1.h', 1),
>> ('/home/ratmice/tests/macro1.c', 1)]>
>> macro1.c:18 <gdb.Macro C include_trail=[('/home/ratmice/tests/macro1.c', 16)]>
>> macro1.c:18 <gdb.Macro B=1 include_trail=[('/home/ratmice/tests/macro1.c', 13)]>
>
> 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:
>> >
>> > ?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.
>>
>> 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.
>
> Sorry, I don't follow. ?Did you mean "B" instead of "C"? ?What is the
> problem you see here with "C"? ?It is defined only once, on line 16,
> and so is in effect on line 18. ?I see no issues here. ?What am I
> missing?

No, I mean "C".

>> macro1.c:18: ?foo(); 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 location'
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 effect?
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 (<gdb.Macro 0x.......>, <gdb.Macro 0x.....>),

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
>> >
>> > ?Returns @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)
>
> This is marginal enough to have a special exception:
>
> ?Returns @code{True} if the macro accepts an argument list. ?A
> ?function-like macro that accepts an empty argument list also yields
> ?@code{True}.
>

ok, thanks.