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

[Eli Zaretskii <eliz@gnu.org>]

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

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

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

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

> +@defmethod Symtab macros
> +Return all of the macros contained in the symbol table.
> +@end defmethod

Return what, exactly? only their names? something else?

> +@code{gdb.Macro} class.  For obtaining a @code{gdb.Macro} object see
> +@xref{Symbol Tables In Python}.

You want "see @ref".  @xref produces a capitalized "Note:", which will
look as bad English; use @xref only at the beginning of a sentence.

> +@code{gdb.Macro} methods may produce a lazily created python copy from
                                                         ^^^^^^
"Python".

> +gdb's internal representation possibly returning different copies
   ^^^
@value{GDBN}

> +The @code{gdb.Macro} class should be considered an abstract class,
> +instances possibly being of different types.  Thus, you should always call
> +its functions directly from an instance, And never reference a method
                                            ^^^
"and"

> +@defmethod Macro argv
> +Returns a list of the macros arguments if the macro is function like.
> +If the macro is not function like, returns @code{None}

 Returns the argument list of the macro, or @code{None} if the macro
 does not accept arguments.

> +@defmethod Macro definition
> +Returns a string containing the definition of the macro.
> +@end defmethod

 Returns a string containing the macro body.

> +@defmethod Macro include_trail
> +Returns a list of tuples containing the filenames, and line numbers
                                                    ^
This comma is redundant.

> +of header and source files that correspond to the include directives,
> +and location of definition.  The list is sorted starting with the place
> +of definition, and ending with the first include directive.
> +@end defmethod

An example of this list of tuples would go a long way towards making
this description more clear.

> +@defmethod Macro is_function_like
> +Returns @code{True} If the macro is function like.
> +@end defmethod

  Returns @code{True} if the macro accepts arguments.

> +@defmethod Macro is_valid
> +Returns @code{True} if the macro is valid.

And presumably False otherwise.

> +All other @code{gdb.Macro} methods will throw an exception if the object is

What exception?  Is that important to document?

> +invalid at the time the method is called.
> +A macro which becomes invalid will never be valid again
> +without looking up the macro again to create a new @code{gdb.Macro}
> +object.
> +@end defmethod

Please tell here what does it mean for a macro to be "valid".  Also,
how to "look up the macro again".  Finally, it sounds like this method
should be the first one documented, as it is the only one that is
always usable.

Thanks.