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

[Andrew Burgess <andrew.burgess@embecosm.com>]

* 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.' ?

How about that?

> 
> > +@findex gdb.add_history
> 
> You don''t need @findex here, since @defun produces that
> automatically.

OK, thanks.

> 
> > +Append @var{value}, an instance of @code{gdb.Value} (@pxref{Values
> > +From Inferior}), to @value{GDBN}'s value history (@pxref{Value
> 
> This sounds like it appends the Python object to the history, but in
> reality it appends its value, right?

You're absolutely correct, but does the user care?  If the user tries
to get the value back from the history list in Python then they will
always get a gdb.Value object returned, though not the same object, it
will represent the same value.

I guess I'm just wondering if the extra complexity of explaining how
this works actually helps the user at all?

Anyway, here's my attempt to explain all this:

  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.

Thoughts?

> 
> > +History}) and return an integer, its history number.  If @var{value}
>             ^
> Comma missing there.

OK, thanks.

Thanks,
Andrew