[RFA/doco] Document "set/show print frame-arguments"

[RFA/doco] Document "set/show print frame-arguments"

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 371 bytes --]

Hello,

Here is the documentation related to the "set/show print frame-arguments"
that I recently added.

2007-11-09  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Print Settings): Add documentation for "set/show
        print frame-arguments".

I am debating whether the last paragraphe should be merged with the
first one, or not...

Thanks,
-- 
Joel

[-- Attachment #2: args-doc.diff --]
[-- Type: text/plain, Size: 1890 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.442
diff -u -p -r1.442 gdb.texinfo
--- gdb.texinfo	5 Nov 2007 11:32:31 -0000	1.442
+++ gdb.texinfo	9 Nov 2007 18:37:05 -0000
@@ -6250,6 +6250,41 @@ identical repetitions, instead of displa
 themselves.  Setting the threshold to zero will cause all elements to
 be individually printed.  The default threshold is 10.
 
+@item set print frame-arguments @var{value}
+This command allows to control how the value of arguments are printed
+when the debugger prints a frame (@pxref{Frames}).  The possible
+values are:
+
+@table @code
+@item all
+The value of all arguments is printed.  This is the default.
+
+@item scalars
+Print the value of an argument only if it is a scalar.  The value of more
+complex arguments such as arrays, structures, unions, etc, is replaced
+by @code{...}. Here is an example where only scalar arguments are shown:
+
+@smallexample
+#1  0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) at frame-args.c:23
+@end smallexample
+
+@item none
+None of the argument values are printed.  Instead, the value of each argument
+is replaced by @code{...}. In this case, the example above now becomes:
+
+@smallexample
+#1  0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) at frame-args.c:23
+@end smallexample
+@end table
+
+By default, all argument values are always printed. But this command
+can be useful to make a backtrace more readable, for instance, by
+reducing the amount of information printed for each frame, particularly
+when large objects would normally be printed.
+
+@item show print frame-arguments
+Show how the value of arguments should be displayed when printing a frame.
+
 @item show print repeats
 Display the current threshold for printing repeated identical
 elements.

Re: [RFA/doco] Document "set/show print frame-arguments"

[Eli Zaretskii]

> Date: Fri, 9 Nov 2007 11:13:00 -0800
> From: Joel Brobecker <brobecker@adacore.com>
> 
> 2007-11-09  Joel Brobecker  <brobecker@adacore.com>
> 
>         * gdb.texinfo (Print Settings): Add documentation for "set/show
>         print frame-arguments".

What about NEWS?

Re: [RFA/doco] Document "set/show print frame-arguments"

[Eli Zaretskii]

> Date: Fri, 9 Nov 2007 11:13:00 -0800
> From: Joel Brobecker <brobecker@adacore.com>
> 
> Here is the documentation related to the "set/show print frame-arguments"
> that I recently added.

Thanks!

> I am debating whether the last paragraphe should be merged with the
> first one, or not...

It could be either way, I think.

> +@item set print frame-arguments @var{value}
> +This command allows to control how the value of arguments are printed
> +when the debugger prints a frame (@pxref{Frames}).  The possible
> +values are:

Some @cindex entry here would be useful, I think.  Please think what
phrase(s) you would try to use to look up this subject in the index,
and add index entries with those phrases.

> +@item all
> +The value of all arguments is printed.  This is the default.

I think you should use "values", in plural.  And likewise above, in
the description of the command: "value of arguments are printed"
doesn't sound right.

> +Print the value of an argument only if it is a scalar.  The value of more
> +complex arguments such as arrays, structures, unions, etc, is replaced
> +by @code{...}. Here is an example where only scalar arguments are shown:

Please use @dots{} here and elsewhere, it looks better in print.

> +@smallexample
> +#1  0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) at frame-args.c:23
> +@end smallexample

This line is too long, it will overflow the page margins.  Please
break it into two line, each one preferably shorter than 70
characters.

> +is replaced by @code{...}. In this case, the example above now becomes:
                            ^^
Two spaces after a period that ends a sentence, here and elsewhere,
please.

> +By default, all argument values are always printed. But this command
> +can be useful to make a backtrace more readable, for instance, by
> +reducing the amount of information printed for each frame, particularly
> +when large objects would normally be printed.

Don't you want to mention the Adacore case, which was the reason for
this feature?

> +
> +@item show print frame-arguments
> +Show how the value of arguments should be displayed when printing a frame.
> +
>  @item show print repeats
>  Display the current threshold for printing repeated identical
>  elements.
> 
> --WYTEVAkct0FjGQmd--
> 

Re: [RFA/doco] Document "set/show print frame-arguments"

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 1317 bytes --]

> Please use @dots{} here and elsewhere, it looks better in print.

Should I use that in @smallexample too? I didn't think it would
make sense, but let me know.

> > +By default, all argument values are always printed. But this command
> > +can be useful to make a backtrace more readable, for instance, by
> > +reducing the amount of information printed for each frame, particularly
> > +when large objects would normally be printed.
> 
> Don't you want to mention the Adacore case, which was the reason for
> this feature?

I wasn't really sure of that, because we're working on the performance
aspect too.  We think we've improved a little bit already.  But on the
other hand, it's true that the only real solution to ultimate performance
is through the use of pure DWARF, which is still a ways away (and AdaCore
is also still supporting targets where DWARF is not available). So your
suggestion was indeed a good idea, and I followed it.


2007-11-10  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Print Settings): Add documentation for "set/show
        print frame-arguments".

I'm also attaching the NEWS entry, which I did forget (good catch!).

2007-11-10  Joel Brobecker  <brobecker@adacore.com>

        * NEWS: Add entry for new set/show print frame-args command.

Thanks, Eli.
-- 
Joel

[-- Attachment #2: doc-frame-args.diff --]
[-- Type: text/plain, Size: 2388 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.442
diff -u -p -r1.442 gdb.texinfo
--- gdb.texinfo	5 Nov 2007 11:32:31 -0000	1.442
+++ gdb.texinfo	10 Nov 2007 18:09:46 -0000
@@ -6250,6 +6250,51 @@ identical repetitions, instead of displa
 themselves.  Setting the threshold to zero will cause all elements to
 be individually printed.  The default threshold is 10.
 
+@item set print frame-arguments @var{value}
+@cindex printing frame argument values
+@cindex print all frame argument values
+@cindex print frame argument values for scalars only
+@cindex do not print frame argument values
+This command allows to control how the values of arguments are printed
+when the debugger prints a frame (@pxref{Frames}).  The possible
+values are:
+
+@table @code
+@item all
+The values of all arguments are printed.  This is the default.
+
+@item scalars
+Print the value of an argument only if it is a scalar.  The value of more
+complex arguments such as arrays, structures, unions, etc, is replaced
+by @dots{}. Here is an example where only scalar arguments are shown:
+
+@smallexample
+#1  0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green)
+  at frame-args.c:23
+@end smallexample
+
+@item none
+None of the argument values are printed.  Instead, the value of each argument
+is replaced by @dots{}.  In this case, the example above now becomes:
+
+@smallexample
+#1  0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...)
+  at frame-args.c:23
+@end smallexample
+@end table
+
+By default, all argument values are always printed.  But this command
+can be useful in several cases.  For instance, it can be used to reduce
+the amount of information printed in each frame, making the backtrace
+more readable.  Also, this command can be used to improve performance
+when displaying Ada frames, because the computation of large arguments
+can sometimes be CPU-intensive, especiallly in large applications.
+Setting @code{print frame-arguments} to @code{scalars} or @code{none}
+avoids this computation, thus speeding up the display of each Ada frame.
+
+@item show print frame-arguments
+Show how the value of arguments should be displayed when printing a frame.
+
 @item show print repeats
 Display the current threshold for printing repeated identical
 elements.

[-- Attachment #3: NEWS.diff --]
[-- Type: text/plain, Size: 643 bytes --]

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.246
diff -u -p -r1.246 NEWS
--- NEWS	25 Oct 2007 05:57:58 -0000	1.246
+++ NEWS	10 Nov 2007 18:13:49 -0000
@@ -3,6 +3,13 @@
 
 *** Changes since GDB 6.7
 
+* New commands
+
+set print frame-arguments (all|scalars|none)
+show print frame-arguments
+  The value of this variable can be changed to control which argument
+  values should be printed by the debugger when displaying a frame.
+
 * GDB can now be built as a native debugger for debugging Windows x86
 (mingw32) Portable Executable (PE) programs.
 

Re: [RFA/doco] Document "set/show print frame-arguments"

[Eli Zaretskii]

> Date: Sat, 10 Nov 2007 10:19:55 -0800
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > Please use @dots{} here and elsewhere, it looks better in print.
> 
> Should I use that in @smallexample too?

Sure, why not?

> +is replaced by @dots{}.  In this case, the example above now becomes:

@code{@dots{}}

Also, there's still one place with only one space after a period that
ends a sentence.

Otherwise, fine with me.  Thanks!

Re: [RFA/doco] Document "set/show print frame-arguments"

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 571 bytes --]

> > > Please use @dots{} here and elsewhere, it looks better in print.
> > 
> > Should I use that in @smallexample too?
> 
> Sure, why not?

I was thinking that the @smallexample should probably be a verbatim
copy of debugger output, and so the style should be consistent. But
I used @dots like you said.

> > +is replaced by @dots{}.  In this case, the example above now becomes:
> 
> @code{@dots{}}

Oups, fixed.

> Otherwise, fine with me.  Thanks!

Thanks. Attached is what I ended up checking in. The NEWS change is
also now in.

Thanks for your help, Eli.
-- 
Joel

[-- Attachment #2: doc-frame-args.diff --]
[-- Type: text/plain, Size: 2455 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.442
diff -u -p -r1.442 gdb.texinfo
--- gdb.texinfo	5 Nov 2007 11:32:31 -0000	1.442
+++ gdb.texinfo	12 Nov 2007 05:11:01 -0000
@@ -6240,6 +6240,51 @@ Setting  @var{number-of-elements} to zer
 Display the number of elements of a large array that @value{GDBN} will print.
 If the number is 0, then the printing is unlimited.
 
+@item set print frame-arguments @var{value}
+@cindex printing frame argument values
+@cindex print all frame argument values
+@cindex print frame argument values for scalars only
+@cindex do not print frame argument values
+This command allows to control how the values of arguments are printed
+when the debugger prints a frame (@pxref{Frames}).  The possible
+values are:
+
+@table @code
+@item all
+The values of all arguments are printed.  This is the default.
+
+@item scalars
+Print the value of an argument only if it is a scalar.  The value of more
+complex arguments such as arrays, structures, unions, etc, is replaced
+by @code{@dots{}}.  Here is an example where only scalar arguments are shown:
+
+@smallexample
+#1  0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
+  at frame-args.c:23
+@end smallexample
+
+@item none
+None of the argument values are printed.  Instead, the value of each argument
+is replaced by @code{@dots{}}.  In this case, the example above now becomes:
+
+@smallexample
+#1  0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
+  at frame-args.c:23
+@end smallexample
+@end table
+
+By default, all argument values are always printed.  But this command
+can be useful in several cases.  For instance, it can be used to reduce
+the amount of information printed in each frame, making the backtrace
+more readable.  Also, this command can be used to improve performance
+when displaying Ada frames, because the computation of large arguments
+can sometimes be CPU-intensive, especiallly in large applications.
+Setting @code{print frame-arguments} to @code{scalars} or @code{none}
+avoids this computation, thus speeding up the display of each Ada frame.
+
+@item show print frame-arguments
+Show how the value of arguments should be displayed when printing a frame.
+
 @item set print repeats
 @cindex repeated array elements
 Set the threshold for suppressing display of repeated array