Re: [PATCH 9/9] add python layer

[Eli Zaretskii <eliz at gnu dot org>]

> From: Tom Tromey <tromey@redhat.com>
> Date: Fri, 07 Sep 2012 12:51:15 -0600
> 
> --- a/gdb/NEWS
> +++ b/gdb/NEWS

OK for this part.

> +@command{info type-printers} displays all the available type printers.

I think we use @code for GDB commands.  @command is for shell commands.

> +@node Type Printing API
> +@subsubsection Type Printing API

Please add a @cindex entry here.  Something like this:

 @cindex type printing API for python

> +A @dfn{type printer} is just a Python object conforming to a certain
> +protocol.

Whenever introducing a new term, it is generally a good idea to have a
@cindex entry for that term, in this case "@cindex type printer".

>+            A simple base class implementing the protocol is provided;
> +@xref{gdb.types}.  A type printer must supply at least:

@xref is only for the beginning of a sentence (it produces a
capitalized "See").  Here you want "see @ref" instead.

> +@defivar type_printer enabled
> +A boolean which is True if the printer is enabled, and False
> +otherwise.  This is manipulated by the @command{enable type-printer}
> +and @command{disable type-printer} commands.

Please use @code for commands, here and elsewhere.

> +@value{GDBN} will call the @code{instantiate} method of each enabled
> +type printer.  If this method returns @code{None}, then the result is
> +ignored; otherwise, it is appended to the list of recognizers.

You probably want to tell that the result should be the 'recognize'
method (IIUC), if it isn't 'None'.

> +Then, when @value{GDBN} is going to display a type name, it iterates
> +over the list of recognizers.  For each one, it calls the recognition
> +function:
> +
> +@defmethod type_recognizer recognize (self, type)
> +If @var{type} is not recognized, return @code{None}.  Otherwise,
> +return a string which is to be printed as the name of @var{type}.
> +@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
> +Python}).
> +@end defmethod

Is it true that the traversal of the list of recognizers ends when
some recognizer returns a string?  If so, this should be mentioned
here.  If the traversal does not end, we should tell what happens with
all the strings returned by several recognizers.

> +@value{GDBN} uses this two-pass approach so that type printers can
> +efficiently cache information without holding on to it too long.

I think I understand what you mean, but perhaps you should tell a bit
more about this, so that we are sure everyone will understand it.

Thanks.