This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH 9/9] add python layer
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Tom Tromey <tromey at redhat dot com>
- Cc: gdb-patches at sourceware dot org
- Date: Sat, 08 Sep 2012 11:16:46 +0300
- Subject: Re: [PATCH 9/9] add python layer
- References: <87r4qdhdjw.fsf@fleche.redhat.com>
- Reply-to: 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.