[RFAv2,3/3] NEWS and documentation for $_gdb_setting and $_gdb_int_setting.

---
 gdb/ChangeLog       |  3 +++
 gdb/NEWS            |  5 +++++
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo | 48 +++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 61 insertions(+)

> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Fri,  5 Jul 2019 21:58:23 +0200
> 
> +@item $_gdb_setting (@var{setting})
> +@findex $_gdb_setting@r{, convenience function}
> +Return the value of the @value{GDBN} @var{setting} as a string.
> +@var{setting} is any setting that can be used in a @code{set} or
> +@code{show} command (@pxref{Controlling GDB}).

After reading the description of $_gdb_int_setting, a question I have
about this function is whether it works for settings whose values are
integers.  The examples answer that question, but I think the text
should be explicit about that.

> +@item $_gdb_int_setting (@var{setting})
> +@findex $_gdb_int_setting@r{, convenience function}
> +Return the value of the @value{GDBN} @var{setting} as an integer.
> +This only works for boolean, auto boolean and integer settings.
> +The boolean values @code{on} and @code{off} are converted to
> +the integer values @code{0} and @code{1}.

The correspondence of ON and OFF to zero and 1 respectively surprised
me.  Why not the other way around?

>                                             The value @code{auto} is
> +converted to the value  @code{2}.
> +Some integer settings accepts an @code{unlimited} value.
> +Depending on the setting, the unlimited value is converted to a @code{0}
> +or a @code{-1} value.

The last part begs a question how to know whether 'unlimited' will
yield zero or -1?  Can't we always return -1?

Markup-wise, please use @code{@minus{}1}, it will look better in print.

Btw, do we have a way of determining whether a given convenience
function exists in the current GDB?  For variables, one can use
$_isvoid, I think, but what about functions?

Thanks.

Thanks for the comments, I have just sent a v3 that handles
them.

(note that v2 did not change anything compared to v1, as I forgot
to commit the changes before sending the mail).

Some more feedback below.


On Sat, 2019-07-06 at 09:23 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Fri,  5 Jul 2019 21:58:23 +0200
> > 
> > +@item $_gdb_setting (@var{setting})
> > +@findex $_gdb_setting@r{, convenience function}
> > +Return the value of the @value{GDBN} @var{setting} as a string.
> > +@var{setting} is any setting that can be used in a @code{set} or
> > +@code{show} command (@pxref{Controlling GDB}).
> 
> After reading the description of $_gdb_int_setting, a question I have
> about this function is whether it works for settings whose values are
> integers.  The examples answer that question, but I think the text
> should be explicit about that.
I have tried to clarify this in the description in RFAv3.

> 
> > +@item $_gdb_int_setting (@var{setting})
> > +@findex $_gdb_int_setting@r{, convenience function}
> > +Return the value of the @value{GDBN} @var{setting} as an integer.
> > +This only works for boolean, auto boolean and integer settings.
> > +The boolean values @code{on} and @code{off} are converted to
> > +the integer values @code{0} and @code{1}.
> 
> The correspondence of ON and OFF to zero and 1 respectively surprised
> me.  Why not the other way around?
That was an error in the doc, fixed in RFAv3.  It now describes
that 0 is off and 1 is on.

> 
> >                                             The value @code{auto} is
> > +converted to the value  @code{2}.
> > +Some integer settings accepts an @code{unlimited} value.
> > +Depending on the setting, the unlimited value is converted to a @code{0}
> > +or a @code{-1} value.
> 
> The last part begs a question how to know whether 'unlimited' will
> yield zero or -1?  Can't we always return -1?
I think it is better to keep the same convention as what is accepted
by the "set" command: some settings are using 0 to mean unlimited
and some are using -1.
I have tried to describe this in the doc RFAv3.

> 
> Markup-wise, please use @code{@minus{}1}, it will look better in print.
> 
> Btw, do we have a way of determining whether a given convenience
> function exists in the current GDB?  For variables, one can use
> $_isvoid, I think, but what about functions?

I do not know of any way to see if a user defined function or convenience
function is defined.
For the GDB convenience function, the GDB major/minor can be used to 
determine what is available.

Philippe

> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: gdb-patches@sourceware.org
> Date: Sat, 06 Jul 2019 12:54:39 +0200
> 
> > The last part begs a question how to know whether 'unlimited' will
> > yield zero or -1?  Can't we always return -1?
> I think it is better to keep the same convention as what is accepted
> by the "set" command: some settings are using 0 to mean unlimited
> and some are using -1.
> I have tried to describe this in the doc RFAv3.

The new text is OK, but I'd suggest to say in addition something like
"See the documentation of the corresponding @code{set} command for
the numerical value equivalent to @code{unlimited}."

> > Btw, do we have a way of determining whether a given convenience
> > function exists in the current GDB?  For variables, one can use
> > $_isvoid, I think, but what about functions?
> 
> I do not know of any way to see if a user defined function or convenience
> function is defined.
> For the GDB convenience function, the GDB major/minor can be used to 
> determine what is available.

OK, thanks.