Re: [python][patch] Inferior and Thread information support.

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 24 May 2010 13:18:10 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
> 
> This patch adds Python support to inferiors and threads.

Thanks.  A few comments about the documentation parts:

> +@node Inferiors In Python
> +@subsubsection Inferiors In Python

It is usually a good idea to have a @cindex entry at the beginning of
a section whose name is identical to the section name (except all
lower-case).

> +Programs which are being run under @value{GDBN} are called inferiors
> +(@pxref{Inferiors and Programs}).  Python scripts can access
> +information about and manipulate inferiors controlled by @value{GDBN}
> +via objects of the @code{gdb.Inferior} class.

This should probable have a @findex entry for gdb.Inferior.

> +@defmethod Inferior threads
> +This method returns a tuple holding all the threads which are valid
> +when it is called.  If there are no valid threads, the method will
> +return an empty list.

Are "list" and "tuple" synonyms in Python?  If not, perhaps this needs
a slight rewording.

> +@defmethod Inferior read_memory @var{address} @var{length}

I don't think you need @var around the arguments of this method (or
any other methods in the patch).  You only need @var if an argument
includes characters treated specially by Texinfo.

> +Write the contents of @var{buffer} (a Python object which supports the
> +buffer protocol, i.e., a string, an array or the object returned from
> +@code{gdb.read_memory}) to the inferior, starting at @var{address}.

I wonder whether a buffer object warrants a separate short description
which is not in parens in the middle of describing a method.

> +@defmethod Inferior search_memory @var{address} @var{length} @var{pattern} @r{[}@var{size}@r{]} @r{[}@var{max_count}@r{]}
> +Search a region of the inferior memory starting at @var{address} with the
> +given @var{length}.  @var{pattern} can be a string, a byte array, a buffer
> +object, a number, a @code{gdb.Value} object (@pxref{Values From Inferior})
> +or a list or tuple with elements in any combination of those types.

The semantics of tuple or list as PATTERN is not explained here.

>                                                         If @var{size} is
> +zero or not specified, it is taken from the value's type in the current
> +language.

What does this mean if PATTERN is a tuple or a list?

>             This is useful when one wants to specify the search pattern as
> +a mixture of types.

Is "mixture of types" intended to cover the list/tuple case?  If so, I
suggest to use identical words, to minimize the chance of confusing
the reader with terminology that is never explained.

> +@node Threads In Python
> +@subsubsection Threads In Python

See the comment above regarding a @cindex entry here.

> +Python scripts can access information about, and manipulate inferior threads
> +controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.

And @findex here regarding gdb.InferiorThread.

> +@defivar InferiorThread num
> +ID of the thread, as assigned by GDB.
                                    ^^^
@value{GDBN}.

Okay with those changes.

In addition, I think we need a NEWS entry for these features.

Thanks.