Re: [PATCHv2] gdb/python: add facility to add values into the history

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 26 Aug 2021 10:20:02 +0100
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: gdb-patches@sourceware.org
> 
> * Eli Zaretskii <eliz@gnu.org> [2021-08-25 21:01:50 +0300]:
> 
> > > From: Andrew Burgess <andrew.burgess@embecosm.com>
> > > Date: Wed, 25 Aug 2021 18:27:19 +0100
> > > 
> > > +* Python API
> > > +
> > > +  ** New function gdb.add_history(), which takes a gdb.Value object
> > > +     and adds the value to GDB's history list.  An integer, the index
> >                  ^^^^^^^^^
> > "its value", right?
> 
> I don't know, that doesn't sound right to me.  'its value' seems to
> imply a value that belongs to someone/something, but I don't think
> that's the case here.
> 
> Maybe, '...takes a gdb.Value object and adds it to GDB's history list.' ?

No, that's worse, because you don't add the Python object to the
history.

How about if you use the same wording you suggested for the manual:
"the value it represents"?

>   Takes @var{value}, an instance of @code{gdb.Value} (@pxref{Values From
>   Inferior}), and appends the value this object represents to
>   @value{GDBN}'s value history (@pxref{Value History}) and return an
>   integer, its history number.  If @var{value} is not a
>   @code{gdb.Value}, it is is converted using the @code{gdb.Value}
>   constructor.  If @var{value} can't be converted to a @code{gdb.Value}
>   then a @code{TypeError} is raised.

This text is fine, thanks.