Re: Python pretty-printing [5/6]

[Eli Zaretskii <eliz at gnu dot org>]

> From: Tom Tromey <tromey@redhat.com>
> Date: Thu, 02 Apr 2009 14:56:55 -0600
> 
> This is the main part of the pretty-printing code.

Thanks.

> It adds a new "/r" ("raw") option to the print command family.

But this change in behavior is not documented in the docs patch,
right?

> 2009-04-01  Tom Tromey  <tromey@redhat.com>
> 	    Thiago Jung Bauermann  <bauerman@br.ibm.com>
> 	    Phil Muldoon  <pmuldoon@redhat.com>
> 
> 	* gdb.texinfo (Objfiles In Python): Reference pretty printing.
> 	(Pretty Printing): New node.
> 	(Python API): Update.

Comments:

> +@node Pretty Printing
> +@subsubsection Pretty Printing

Please add a @cindex entry here suitable for this subsection.

> +A pretty-printer is an object that implements a specific interface.
> +There is no predefined base class for pretty-printers.

Is it possible to expand this a bit?  This explanation did not explain
anything to me; I needed to read the whole text below several times,
and then look at the code and think, before I managed to come up with
some vague idea of what this feature offers me, and what I can and
cannot do with it.

> +When printing from the CLI, if the @code{to_string} method exists,
> +then @value{GDBN} will prepend its result to the values returned by
> +@code{children}.

I suggest an example here of what is, or could be, prepended.

> +If this method returns a string, it is printed verbatim.  Otherwise,
> +the result is converted to a @code{gdb.Value}, following the usual
> +algorithm.

If we describe the "usual algorithm" somewhere, a cross-reference here
would be a good idea.

>            Then @value{GDBN} prints this value; this may possibly
> +result in a call to another pretty-printer.  If the result is not
> +convertible to @code{gdb.Value}, an exception is raised.

Should we say what exception is raised?

> +@subsubsection Selecting Pretty-Printers

Please make this a @node, and please add a @cindex entry for it.

>                                       A function on one of these lists
> +takes a single @code{gdb.Value} argument and returns a pretty-printer
> +object conforming to the interface definition above.

I presume that "above" refers to the previous section, right?  If so,
please add a cross-reference.

> +We recommend that you put your core pretty-printers into a versioned
> +python package, and then restrict your auto-loaded code to idempotent
> +behavior -- for example, just @code{import}s of your printer modules,

Please use "---" (3 dashes) for em-dash.

> +@smallexample
> +def register_printers (objfile):
> +    objfile.pretty_printers.add (str_lookup_function)
> +@end smallexample
> +
> +And then the corresponding contents of the auto-load file would be:

I think you want @noindent before "And then ...", because it is
logically a continuation of the previous example, not a new paragraph.