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

Andrew Burgess via Gdb-patches
2022-05-30T09:55:46Z

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.

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!

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.

Thanks,
Andrew

>
> @subheading Registering a Unwinder
> --
> 2.25.1