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

[Matt Rice <ratmice at gmail dot com>]

On Fri, Aug 26, 2011 at 3:42 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, 26 Aug 2011 01:04:21 -0700
>> From: Matt Rice <ratmice@gmail.com>
>> Cc: gdb-patches@sourceware.org
>>
>> >> 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)]>
>> > [...]
>> >> > ?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?
>
> Now I'm utterly confused. ?The output of `macros' shows not just C,
> but also AMACRO and B. ?All of them are "in effect" in line 18. ?So
> why are you talking only about C? ?The fact that it's actually
> mentioned in that line seems irrelevant, because you are documenting
> what the `macros' method returns. ?What am I missing here?

That Symtab_and_line represents that single source line, and if we use
'in effect',
without explicitly qualifying the scope under consideration,
we leave the user to decide under what scope macros are considered to
be in effect.
and the user's idea of that scope may or may not match the actual
scope that the function uses.

e.g. it could be from `0 - line' as it is, or it could be 'macros used
from line - line end'
(which is a function we do not even implement.)


>> 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.
>
> How is this different from my suggestion above?

It explicitly specifies a scope as 'defined before the source line given...'

>> >> >> +@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.....>),
>
> What are the 0x.... numbers here?

The addresses of the python objects.