Re: [RFC][python] Fixes and improvements to gdb.Value.

[Tom Tromey <tromey at redhat dot com>]

>>>>> "Thiago" == Thiago Jung Bauermann <bauerman@br.ibm.com> writes:

>> > +@findex gdb.history
>> 
>> The text below this does not mention "gdb.history" at all.  Should it?
>> I could imagine a reader who gets here by following the "gdb.history"
>> index entry, and is then puzzled by not finding that text anywhere.

Thiago> Well, the text is in the section which describes functions in the gdb
Thiago> module, so the reader should be aware that the function is inside it.
Thiago> Also, in Python "gdb.history" wouldn't be the only possible way of
Thiago> referencing the function. If the user imports the gdb module with
Thiago> "from gdb import *", then he would just need to type "history" to use
Thiago> it. "gdb.history" is only special in that from the CLI, the gdb module
Thiago> is automatically imported and would be accessible to the user spelled
Thiago> like that. But (s)he could type "python from gdb import *" and then use
Thiago> the other way to access it.

Thiago> In a nutshell, my answer is "no, I don't think it should". :-)

I agree.

Note that the existing Python docs in the manual already use this
approach.  This patch merely continues it.

My reason for adding these index entries is that a Python programmer
might reasonably expect to find the fully-qualified function name in
the manual's index.  However, it is strange to constantly see the
fully-qualified name in the documentation text.  So, I used the short
form in the text and added index entries.

Thiago -- I know it is kind of a pain, but would you mind putting any
changes you make back onto the Python branch?  Or if you can't do it,
let me know and I will try to.  I'd like to keep the branch
"canonical" so that we can diff against mainline to see what Python
bits ought to be merged.

Tom