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

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Fri, 26 Aug 2011 04:17:24 -0700
> From: Matt Rice <ratmice@gmail.com>
> Cc: gdb-patches@sourceware.org
> 
> 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.

I expect the users to know the definition of a macro scope.  Are you
talking about some specific ambiguity, or in general?  If the former,
what is the ambiguity?

> 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.)

"In effect" means that a macro _can_ be used in this line.  I don't
see any ambiguity here, and it surely isn't the job of the GDB manual
to teach the rules of defining and using macros.

> >> 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...'

Which is inaccurate (e.g., what about definitions in other files that
are included by this one?).  Again, it is not our job to document how
macros are defined and used, the reader should already know that,
especially if she is writing a Python script ;-)

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

Then it should be a "list of macro objects specified by their
addresses".