This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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

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

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]