Re: [RFC 4/5] Document changes to info [args|functions|locals|variables]

[Philippe Waroquiers <philippe.waroquiers@skynet.be>]

On Mon, 2018-07-02 at 18:02 +0300, Eli Zaretskii wrote:
Thanks for your comments.
Find some feedback below (no feedback means the comment
was handled as you suggested).
I will resubmit the whole doc for review for the first RFA,
handling your
additional comments on the below, if you have some.

> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Sun,  1 Jul 2018 23:07:33 +0200
> > 
> > Document changes to info [args|functions|locals|variables]
> 
> Thanks, I have a few comments:
> 
> >  gdb/doc/gdb.texinfo | 98 ++++++++++++++++++++++++++++++++++++++++-----
> >  1 file changed, 88 insertions(+), 10 deletions(-)
> 
> Please provide a ChangeLog entry for gdb/doc/ChangeLog.
Will do for the RFA.


> Is there any significance in "contain a match" vs just "match" above?
> If not, I suggest to use the same wording.
Yes, I think that 'contain a match' is the precise condition verified.
Here is the (full) doc for the 'info locals', where I have reworded
the explanation. The other commands have been changed in the same
way.

@item info locals
@kindex info locals [-q]
Print the local variables of the selected frame, each on a separate
line.  These are all variables (declared either static or automatic)
accessible at the point of execution of the selected frame.

The optional flag @samp{-q}, which stands for @samp{quiet}, disables
printing header information and messages explaining why no local variables
have been printed.

@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
Like @kbd{info locals}, but only print the local variables selected
with the provided regexp(s).

If @var{regexp} is provided, print only the local variables whose names
contain a match for regular expression @var{regexp}.

If @var{type_regexp} is provided, print only the local variables whose
types contain a match for regular expression @var{type_regexp}.
The matching is done with the local variable type as printed by the
@code{whatis} command.
If @var{type_regexp} contains space(s), it should be enclosed in single
quote characters.

If both @var{regexp} and @var{type_regexp} are provided, a local variable
is printed only if it respects the two regexps.

The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
combined with the commands @kbd{frame apply} and @kbd{thread apply}.
For example, your program might use Resource Acquisition Is
Initialization types (RAII) such as @code{lock_something_t} : each
local variable of type @code{lock_something_t} automatically places a
lock that is destroyed when the variable goes out of scope.  You can
then list all acquired locks in your program by doing
@smallexample
thread apply all -s frame apply all -s info locals -q -t lock_something_t
@end smallexample
or the equivalent shorter form
@smallexample
tfaas i lo -q -t lock_something_t
@end smallexample

> 
> Also, the above begs the question: what if I specify both REGEXP and
> TYPE_REGEXP?  Is that allowed?
Yes, it is allowed. The doc above now explicitly describes the behaviour
when both REGEXP are provided.

> > +If @var{type_regexp} contains space(s), it should be enclosed in single
> > +quote characters.
> 
> Only single quotes?  Double quotes are not supported?  Should they be?
I do not think there is a need to support double quotes.
E.g. completer.c also only uses single quote to quote completion strings.

> 
> Do we have "RAII" explained anywhere in the manual?  I don't think so,
> in which case we should have here what it stands for.
I have tried to explain RAII in the doc above, but wondering if that
is clear enough.
If not, we might maybe put a reference to e.g. the wikipedia article 
https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization
if such references are deemed ok in the GDB manual.

Thanks again for the review

Philippe