Re: [patch][python] Implement Python lazy strings (PR 10705)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 08 Jan 2010 14:52:23 +0000
> From: Phil Muldoon <pmuldoon@redhat.com>
> 
> This patch implements Python lazy strings, and also alters the Python
> pretty-printing process to handle them accordingly.

Thanks.

> Index: gdb/doc/gdb.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
> retrieving revision 1.656
> diff -u -r1.656 gdb.texinfo
> --- gdb/doc/gdb.texinfo	6 Jan 2010 20:31:28 -0000	1.656
> +++ gdb/doc/gdb.texinfo	8 Jan 2010 14:22:47 -0000

A few comments about this part.

> +If the optional @var{encoding} argument is given, it must be a string
> +naming the encoding of the @code{gdb.LazyString}. Some examples are:
                                                   ^^
Two spaces, please.

> +@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}.

@code{"foo"} looks funny in the Info manual (because @code encloses
its argument in another pair of quotes.  I suggest @samp{ascii}
etc. (without quotes) instead.  (Yes, I know we use @code{"foo"}
elsewhere in the manual; they need to be fixed as well.)

> +When a lazy string is printed, the @value{GDBN} codec machinery is
> +used to convert the string during printing.

We don't use ``codec'' for GDB encodings.  I suggest to use
``encoding'' here, and perhaps also add a @pxref to the section where
that is described.

> If @var{encoding} is set to @code{None}

Is it None or "None" (a string)?  If the former, then your original
statement that it should be a string, seems to be inaccurate.

> or if @var{encoding} is an empty string,
> +@value{GDBN} will automatically select the encoding most suitable for
> +the string type.

This leaves me wondering what will happen if I don't specify the
encoding at all, and how is that different from specifying None.

Also, what happens if the encoding is not known or not supported by
GDB?

> +If the optional @var{length} argument is given, the string will be
> +fetched and encoded to the length of characters specified.
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^
"to the number of characters" is better, I think.  By the way, does it
count characters or bytes?

> +@node Lazy Strings In Python
> +@subsubsection Python representation of lazy strings.
> +
> +@cindex lazy strings in python
> +@tindex gdb.LazyString

It would be good to say here what is a lazy string, before you start
using it to explain other matters.  Something like

  A @dfn{lazy string} is a string whose contents is not produced until
  it is needed.

> +A @code{gdb.LazyString} can be defined as an @code{address} that

"can be defined" or "is represented in GDB"?  That is, you are
describing the actual implementation, not a possibility, right?

> +@defivar LazyString type
> +This attribute holds the type that is represented by the lazy string's
> +type.  This attribute is not writable.
> +@end defivar

What could be a type of a string, except string?  I think the possible
types should be stated here.