Eli Zaretskii wrote:
>> +@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.

Right. Added a couple.
 
>> +@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.

Agreed. It's a useful assumption.
 
> 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.

I mostly agree, but in some cases I believe examples are not necessary
because IMHO some basic programming skills can be assumed, and a Python
integer is the same as an integer in any other language (I believe you are
referencing to my Python integer example). Examples for such cases will
most likely be obvious code snippets.

In any case, I added an example for that. If you think it's helpful, it can
stay.

> 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 objective of that paragraph was not to describe features of gdb.Value
available for direct use, but rather to give to the user a rationale of the
existence of the gdb.Value object (as opposed to having GDB return native
Python values). There's not much to describe regarding specific elements
and methods of gdb.Value since it has no element, and just one method which
I explicitly list and describe.

From your comment above, I see that my text was not clear so I tried to
rephrase it. What do you think of this version?

>> +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.

I didn't provide an example originally because I thought that it was clear
enough from the description what the method does and how to use it. I'm
providing an example in this version, even though I think it's kind of
redundant. If you think it helps, it can stay.

This patch also fixes the comments from Daniel. Unfortunately, I just found
out that it won't compile with current CVS since it uses some
builtin_type_* variables which don't exist anymore. :-(

I post it as it is to get the documentation part reviewed, and will work to
fix this problem...
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center