Re: [PATCH v3 4/4] gdb/python doc: Move unwinder skeleton code

Pedro Alves
2022-09-30T16:42:11Z

On 2022-09-30 4:53 p.m., Eli Zaretskii wrote:
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>> Date: Fri, 30 Sep 2022 15:50:20 +0100
>>
>> So I think the manual should be fixed by dropping the "or @code{gdb}", resulting in:
>>
>> Passing @code{None} adds @var{unwinder} to the @value{GDBN}'s global unwinder list.
>>
>> Actually, the "the" in "to the @value{GDBN}'s" looks wrong to me. So I think we
>> should really say:
>>
>> Passing @code{None} adds @var{unwinder} to @value{GDBN}'s global unwinder list.
>
> How about
>
> If @var{locus} is @code{None}, that stands for @value{GDBN}'s global
> unwinder list.
>
> I think this is clearer and less likely to cause misinterpretation.
>

Seems fine in isolation, but looking at the whole paragraph, how about similar text to
what's in gdb/python/lib/gdb/unwinder.py? Seems clear enough to me.

I also noticed a couple instances of "a unwinder", also fixed.

While at it, "GDB proper" seems like a weird conception.

How about this?

From 7c5e7875bed7f4316823db67d95821c88c679daf Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Fri, 30 Sep 2022 17:23:03 +0100
Subject: [PATCH] Python

Change-Id: I98c1b1000e1063815238e945ca71ec6f37b5702e
---
gdb/doc/python.texi | 18 +++++++++---------
1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 2692211f388..4a7b047c3e0 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2861,21 +2861,21 @@ class MyUnwinder(Unwinder):

@end smallexample

-@subheading Registering a Unwinder
+@subheading Registering an Unwinder

-An object file, a program space, and the @value{GDBN} proper can have
-unwinders registered with it.
+Object files and program spaces can have unwinders registered with
+them. In addition, you can also register unwinders globally.

-The @code{gdb.unwinders} module provides the function to register a
+The @code{gdb.unwinders} module provides the function to register an
unwinder:

@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False)
-@var{locus} is specifies an object file or a program space to which
-@var{unwinder} is added. Passing @code{None} or @code{gdb} adds
-@var{unwinder} to the @value{GDBN}'s global unwinder list. The newly
-added @var{unwinder} will be called before any other unwinder from the
+@var{locus} specifies which unwinder list the @var{unwinder} is
+prepended to. It can be either an object file, a program space, or
+@code{None}, in which case the unwinder is registered globally. The
+newly added @var{unwinder} will be called before any other unwinder from the
same locus. Two unwinders in the same locus cannot have the same
-name. An attempt to add a unwinder with already existing name raises
+name. An attempt to add an unwinder with an already existing name raises
an exception unless @var{replace} is @code{True}, in which case the
old unwinder is deleted.
@end defun

base-commit: cfc0ffd31e90972296b81d362a7d83eb60eb21c0
--
2.36.0