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

[Matt Rice <ratmice@gmail.com>]

On Wed, Aug 24, 2011 at 1:09 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: matt rice <ratmice@gmail.com>
>> Cc: matt rice <ratmice@gmail.com>
>> Date: Wed, 24 Aug 2011 08:10:53 -0700
>>
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>> @@ -38,6 +38,13 @@
>>
>>    ** Symbols now provide the "type" attribute, the type of the symbol.
>>
>> +  ** Objfiles now provide a "symtabs" method.
>> +
>> +  ** The Macro object is now available for representing preprocessor macros.
>> +     The following objects now have methods for obtaining macro objects.
>> +     - Symtab_and_line now has a "macro_named" method
>> +     - Symtab now has a "macros" method.
>
> This part is okay, but please add a reference to the section in the
> manual where these are described.

ok, will send a new patch after the we get the below stuff figured out.

>> +@defmethod Symtab_and_line macro_named @r{[}name@r{]}
>> +Returns a @code{gdb.Macro} object, for the macro
>> +with the given name.
>> +@end defmethod
>
> This should say what happens if "name" is omitted.  It's optional,
> right?

Nope, removed the []'s

>> +@defmethod Symtab_and_line macros
>> +Returns all of the macros which are defined and not undefined or redefined,
>
> "not redefined"? what exactly does this mean, and how can GDB
> distinguish between something that is defined and something that is
> defined and then redefined?

the symtab_and_line method distinguishes something that is defined and
then redefined by using the last defined version of the macro (in this
case)

here's an example and later a question

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


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

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

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