[PATCH] Reword gdb.Frame.read_var documentation

[PATCH] Reword gdb.Frame.read_var documentation

[Tom Tromey]

I noticed that the docs for gdb.Frame.read_var are mildly incorrect.
They don't really document how the 'block' argument is handled.  This
patch tries to correct the oversight.
---
 gdb/doc/python.texi | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 8cc3f92cbfe..5eb4c1664b7 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -5719,12 +5719,16 @@ object.
 @end defun
 
 @defun Frame.read_var (variable @r{[}, block@r{]})
-Return the value of @var{variable} in this frame.  If the optional
-argument @var{block} is provided, search for the variable from that
-block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter).  The @var{variable}
-argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
-@code{gdb.Block} object.
+Return the value of @var{variable} in this frame.  @var{variable} must
+be a string or a @code{gdb.Symbol} object.
+
+If @var{variable} is a string, then @var{block} may be provided.  In
+this case, search for the variable from that block; otherwise start at
+the frame's current block (which is determined by the frame's current
+program counter).
+
+If @var{variable} is a @code{gdb.Symbol} object, then @var{block} is
+ignored.
 @end defun
 
 @defun Frame.select ()
-- 
2.40.1

Re: [PATCH] Reword gdb.Frame.read_var documentation

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Mon, 30 Oct 2023 09:08:50 -0600
> 
> I noticed that the docs for gdb.Frame.read_var are mildly incorrect.
> They don't really document how the 'block' argument is handled.  This
> patch tries to correct the oversight.

Thanks.

> +Return the value of @var{variable} in this frame.  @var{variable} must
> +be a string or a @code{gdb.Symbol} object.
> +
> +If @var{variable} is a string, then @var{block} may be provided.  In
> +this case, search for the variable from that block; otherwise start at
> +the frame's current block (which is determined by the frame's current
> +program counter).
> +
> +If @var{variable} is a @code{gdb.Symbol} object, then @var{block} is
> +ignored.

This is okay, but it left me with an unanswered question: if VARIABLE
is a symbol, where does the search for VARIABLE start? does VARIABLE
specify its BLOCK or something?