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

[Eli Zaretskii <eliz@gnu.org>]

> 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?

> 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?

> >> >> +@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?