Re: [rfc] expose gdb values to python

[Eli Zaretskii <eliz@gnu.org>]

> From:  Thiago Jung Bauermann <bauerman@br.ibm.com>
> Date:  Thu, 25 Sep 2008 22:59:26 -0300
> 
> gdb/doc/
> 	* gdb.texinfo. (Values From Inferior): New subsubsection.

This part is approved with a few comments, see below.

> +@node Values From Inferior
> +@subsubsection Values From Inferior

Please add some @cindex entry/entries here, which would be useful for
someone who will look for this stuff via the index.

> +@value{GDBN} provides values it obtains from the inferior program in an
> +object of type @code{gdb.Value}.  This object keeps track of information
> +related to the value such as its type, the address where it is kept in
> +the inferior, and so on.

My assumption in reviewing Python-related manual sections is that the
reader will generally _not_ be a proficient Python programmer, but
rather someone who programs in another language, like C++ or Ada, and
whose use of Python in GDB is just so to get away with whatever
scripting the reader needs to craft for her current needs.

With that in mind, I think we should have as much examples and
specific concrete information in these sections as possible, to make
it easier for the reader to understand how to use these features
without too many detours into Python manuals.  Abstract information,
such as references to Python types, will not alone reach that goal.

For example, in the above paragraph, would it help to describe the
specific elements and methods of `gdb.Value', or give a couple of
examples of their use in real life?  You mention the type and address
of the inferior's value, but are there other useful members that the
reader would want to know about?  And even for these 2, what kind of
data types are they?

> +The following method is provided:
> +
> +@defmethod Value dereference
> +If the @code{gdb.Value} object is of a pointer type, you can dereference
> +it using the @code{dereference} method.  This gives you a new
> +@code{gdb.Value} object for the pointed-to contents.
> +@end defmethod

Again, a practical example of using this would be good to have.

Thanks.