Re: [PATCH v2 1/3] gdb/python doc: Add register_unwinder to code example

[Paulo Neves <ptsneves@gmail.com>]

Hello Andrew

On 5/30/22 11:55, Andrew Burgess wrote:
> Paulo Neves via Gdb-patches<gdb-patches@sourceware.org>  writes:
>
>> It is now clear in the example code that an unwinder needs to be
>> registered to be used.
>> ---
>>   gdb/doc/python.texi | 2 ++
>>   1 file changed, 2 insertions(+)
>>
>> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
>> index cb5283e03c0..5b7fba798a9 100644
>> --- a/gdb/doc/python.texi
>> +++ b/gdb/doc/python.texi
>> @@ -2814,6 +2814,8 @@ class MyUnwinder(Unwinder):
>>           # Return the result:
>>           return unwind_info
>>   
>> +# To use an unwinder it needs to be registered and enabled.
>> +gdb.unwinder.register_unwinder (<locus>, MyUnwinder, replace=<True|False>)
>>   @end smallexample
> I've had reason to read the unwinder example before, and I think it's
> probably my most hated example in our manual.
>
> I absolutely hate that the example is not real, executable, EXAMPLE,
> code, it's just seems like documentation in another form.

I think the fact it was not executable was the reason that nobody
noticed the import was wrong.

>
> That said, I think its not fair for me to require that your additions to
> the existing example be executable, when the rest of the example is
> not.  But, if you _did_ want to improve this whole example, then I'd
> certainly be in favour!

When you mean you want it to be executable, does this mean i should to
remove the meta-values like "<SP number>" sprinkled in the code and
replace them with comments?

Also by real example do you want it to be functional?
I am concerned an example that does any meaningful thing would be confusing.
Something i looked at when trying to get my unwinder working was the
gdb/testsuite/gdb.python/py-unwind.py test. It could be used but adds unrelated logic.

>
> I do however, this that with this addition, the example code is now in
> the wrong place.  Notice your example now makes use of
> `register_unwinder`, but this method is not discussed in detail until
> after the example code.
>
> I think that the whole subsection titled `Unwinder Skeleton Code` should
> be moved later, probably to just before `@node Xmethods In Python`, that
> is, right at the end of the section on unwinders.

I can move the example to the last subsection.

>
> Thanks,
> Andrew
>
>>   
>>   @subheading Registering a Unwinder
>> -- 
>> 2.25.1

I am interested in getting this section improved. Just give me the guidelines to the questions above
and I will prepare the patches.

Paulo Neves