Patchwork [RFC,4/5] Document changes to info [args|functions|locals|variables]

login
register
mail settings
Submitter Philippe Waroquiers
Date July 1, 2018, 9:07 p.m.
Message ID <20180701210734.3793-5-philippe.waroquiers@skynet.be>
Download mbox | patch
Permalink /patch/28181/
State New
Headers show

Comments

Philippe Waroquiers - July 1, 2018, 9:07 p.m.
Document changes to info [args|functions|locals|variables]
---
 gdb/doc/gdb.texinfo | 98 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 88 insertions(+), 10 deletions(-)
Eli Zaretskii - July 2, 2018, 3:02 p.m.
> 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.

> -@item info args
> +@item info args [-q]
>  Print the arguments of the selected frame, each on a separate line.
>  
> +Flag @code{-q}, which stands for @samp{quiet}, disables printing
> +header information and messages explaining why no argument have been
> +printed.

This sentence sounds awkward.  Suggest to rephrase the beginning:

  The optional flag @samp{-q}, which stands for @samp{quiet},
  disables printing ...

> +@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
> +Like @kbd{info args}, but only print the arguments
> +that matches the provided regexp(s).
        ^^^^^^^
"match", in plural.

> +If @var{regexp} is provided, prints only the arguments whose names
                                ^^^^^^
Please be consistent: or "print" everywhere, or "prints" everywhere.

> +If @var{type_regexp} is provided, prints only the arguments whose
> +types contain a match for regular expression @var{type_regexp}.

Is there any significance in "contain a match" vs just "match" above?
If not, I suggest to use the same wording.

Also, the above begs the question: what if I specify both REGEXP and
TYPE_REGEXP?  Is that allowed?

> +The matching is done with the variable type as printed with the
> +@code{whatis} command.                                 ^^^^

"by"

> +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?

Same comments to all the other commands where you introduce these
optional arguments.

> +The command @samp{info locals -q -t @var{type_regexp}} can usefully be
               ^^^^^
@kbd, not @samp.  You are showing a command that the user would type.

> +combined with the commands @samp{frame apply} and @samp{thread apply}.

Likewise.

> +For example, if you have an RAII type @code{lock_something_t},

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.

> +you can list all locks in your program by doing
> +@samp{thread apply all -s frame apply all -s
> +info locals -q -t lock_something_t}, or the equivalent shorter form
> +@samp{tfaas i lo -q -t lock_something_t}.

It is best to show such long commands as @smallexample, broken into
several lines as needed.

Thanks.
Philippe Waroquiers - July 2, 2018, 8:45 p.m.
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
Eli Zaretskii - July 4, 2018, 4:44 p.m.
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: gdb-patches@sourceware.org
> Date: Mon, 02 Jul 2018 22:45:28 +0200
> 
> If both @var{regexp} and @var{type_regexp} are provided, a local variable
> is printed only if it respects the two regexps.

I'd use "matches", not "respects".

> 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

You want @noindent on a separate line before the "or the equivalent",
otherwise the printed manual will have that indented as if it were a
new paragraph (which it isn't).

> I have tried to explain RAII in the doc above, but wondering if that
> is clear enough.

I think it's enough, they can google it if they want to know more.

Thanks, I have no more comments to the new text except the above few
nits.

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7fb6ac5636..789d54a3b2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7705,15 +7705,60 @@  architectures) that you specify in the @code{frame} command.
 @xref{Selection, ,Selecting a Frame}.
 
 @kindex info args
-@item info args
+@item info args [-q]
 Print the arguments of the selected frame, each on a separate line.
 
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no argument have been
+printed.
+
+@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info args}, but only print the arguments
+that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the arguments whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, prints only the arguments whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the variable type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
+
+
 @item info locals
-@kindex 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.
 
+Flag @code{-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
+that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the local variables whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, prints 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 with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
+
+The command @samp{info locals -q -t @var{type_regexp}} can usefully be
+combined with the commands @samp{frame apply} and @samp{thread apply}.
+For example, if you have an RAII type @code{lock_something_t},
+you can list all locks in your program by doing
+@samp{thread apply all -s frame apply all -s
+info locals -q -t lock_something_t}, or the equivalent shorter form
+@samp{tfaas i lo -q -t lock_something_t}.
+
 @end table
 
 @node Frame Filter Management
@@ -17665,32 +17710,65 @@  debugging information, organized into two lists: files whose symbols
 have already been read, and files whose symbols will be read when needed.
 
 @kindex info functions
-@item info functions
+@item info functions [-q]
 Print the names and data types of all defined functions.
 Similarly to @samp{info types}, this command groups its output by source
 files and annotates each function definition with its source line
 number.
 
-@item info functions @var{regexp}
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no functions have been
+printed.
+
+@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}]
 Like @samp{info functions}, but only print the names and data types of
-functions whose names contain a match for regular expression
-@var{regexp}.  Thus, @samp{info fun step} finds all functions whose
+the functions that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the functions whose names
+contain a match for regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose
 names include @code{step}; @samp{info fun ^step} finds those whose names
 start with @code{step}.  If a function name contains characters that
 conflict with the regular expression language (e.g.@:
 @samp{operator*()}), they may be quoted with a backslash.
 
+If @var{type_regexp} is provided, prints only the functions whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the function type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
+Thus, @samp{info fun -t '^int ('} finds the functions that return
+an integer; @samp{info fun -t '(.*int.*'} finds the functions that
+have an argument type containing int; @samp{info fun -t '^int (' ^step}
+finds the functions whose names start with @code{step} and that are returning
+an int.
+
+
 @kindex info variables
-@item info variables
+@item info variables [-q]
 Print the names and data types of all variables that are defined
 outside of functions (i.e.@: excluding local variables).
 The printed variables are grouped by source files and annotated with
 their respective source line numbers.
 
-@item info variables @var{regexp}
+Flag @code{-q}, which stands for @samp{quiet}, disables printing
+header information and messages explaining why no variables have been
+printed.
+
+@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}]
 Like @kbd{info variables}, but only print the names and data types of
-non-local variables whose names contain a match for regular expression
-@var{regexp}.
+non-local variables that matches the provided regexp(s).
+
+If @var{regexp} is provided, prints only the variables whose names
+contain a match for regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, prints only the variables whose
+types contain a match for regular expression @var{type_regexp}.
+The matching is done with the variable type as printed with the
+@code{whatis} command.
+If @var{type_regexp} contains space(s), it should be enclosed in single
+quote characters.
 
 @kindex info classes
 @cindex Objective-C, classes and selectors