[PATCH] btrace, doc: Clarify record function-call-history documentation.

[PATCH] btrace, doc: Clarify record function-call-history documentation.

[Felix Willgerodt]

The documentation for 'record function-call-history' mentions lines instead
of functions when talking about the number of functions printed, as currently
there is only one line printed per function.  Yet the code actually handles
this on function granularity not on line basis.  Future patches will
extend the number of lines printed per function.  This also makes it
consistent with the 'record instruction-history' command, where multiple
lines can be printed per instruction.

gdb/doc/ChangeLog:
2021-06-16  Felix Willgerodt  <felix.willgerodt@intel.com>

	* gdb.texinfo (Process Record and Replay): Stop mentioning lines
	for "record function-call-history" and
	"set record function-call-history-size".
---
 gdb/doc/gdb.texinfo | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d09b86cda95..7cdc83b9537 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7926,15 +7926,14 @@ instruction-history} command.
 @kindex record function-call-history
 @kindex rec function-call-history
 @item record function-call-history
-Prints the execution history at function granularity. It prints one
-line for each sequence of instructions that belong to the same
-function giving the name of that function, the source lines
-for this instruction sequence (if the @code{/l} modifier is
-specified), and the instructions numbers that form the sequence (if
-the @code{/i} modifier is specified).  The function names are indented
-to reflect the call stack depth if the @code{/c} modifier is
-specified.  The @code{/l}, @code{/i}, and @code{/c} modifiers can be
-given together.
+Prints the execution history at function granularity.  For each sequence
+of instructions that belong to the same function, it prints the name of
+that function, the source lines for this instruction sequence (if the
+@code{/l} modifier is specified), and the instructions numbers that form
+the sequence (if the @code{/i} modifier is specified).  The function names
+are indented to reflect the call stack depth if the @code{/c} modifier is
+specified.  The @code{/l}, @code{/i}, and @code{/c} modifiers can be given
+together.
 
 @smallexample
 (@value{GDBP}) @b{list 1, 10}
@@ -7954,7 +7953,7 @@ given together.
 3  bar     inst 11,13   at foo.c:9,10
 @end smallexample
 
-By default, ten lines are printed.  This can be changed using the
+By default, ten functions are printed.  This can be changed using the
 @code{set record function-call-history-size} command.  Functions are
 printed in execution order.  There are several ways to specify what
 to print:
@@ -7970,10 +7969,10 @@ function number @var{func}.  If @var{n} is preceded with @code{-},
 prints @var{n} functions before function number @var{func}.
 
 @item record function-call-history
-Prints ten more functions after the last ten-line print.
+Prints ten more functions after the last ten-function print.
 
 @item record function-call-history -
-Prints ten more functions before the last ten-line print.
+Prints ten more functions before the last ten-function print.
 
 @item record function-call-history @var{begin}, @var{end}
 Prints functions beginning with function number @var{begin} until
@@ -7984,12 +7983,12 @@ This command may not be available for all recording methods.
 
 @item set record function-call-history-size @var{size}
 @itemx set record function-call-history-size unlimited
-Define how many lines to print in the
+Define how many functions to print in the
 @code{record function-call-history} command.  The default value is 10.
-A size of @code{unlimited} means unlimited lines.
+A size of @code{unlimited} means unlimited functions.
 
 @item show record function-call-history-size
-Show how many lines to print in the
+Show how many functions to print in the
 @code{record function-call-history} command.
 @end table
 
-- 
2.25.4

Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928

Re: [PATCH] btrace, doc: Clarify record function-call-history documentation.

[Eli Zaretskii]

> From: Felix Willgerodt <felix.willgerodt@intel.com>
> Cc: markus.t.metzger@intel.com,
> 	eliz@gnu.org,
> 	Felix Willgerodt <felix.willgerodt@intel.com>
> Date: Wed, 16 Jun 2021 14:01:20 +0200
> 
> The documentation for 'record function-call-history' mentions lines instead
> of functions when talking about the number of functions printed, as currently
> there is only one line printed per function.  Yet the code actually handles
> this on function granularity not on line basis.  Future patches will
> extend the number of lines printed per function.  This also makes it
> consistent with the 'record instruction-history' command, where multiple
> lines can be printed per instruction.
> 
> gdb/doc/ChangeLog:
> 2021-06-16  Felix Willgerodt  <felix.willgerodt@intel.com>
> 
> 	* gdb.texinfo (Process Record and Replay): Stop mentioning lines
> 	for "record function-call-history" and
> 	"set record function-call-history-size".

Thanks.

Would someone who knows what the software actually does review the
text, please?  It's okay as far as Texinfo format and conventions go.

RE: [PATCH] btrace, doc: Clarify record function-call-history documentation.

[Metzger, Markus T]

Thanks, Felix,

>> The documentation for 'record function-call-history' mentions lines instead
>> of functions when talking about the number of functions printed, as currently
>> there is only one line printed per function.  Yet the code actually handles
>> this on function granularity not on line basis.  Future patches will
>> extend the number of lines printed per function.  This also makes it
>> consistent with the 'record instruction-history' command, where multiple
>> lines can be printed per instruction.
>>
>> gdb/doc/ChangeLog:
>> 2021-06-16  Felix Willgerodt  <felix.willgerodt@intel.com>
>>
>> 	* gdb.texinfo (Process Record and Replay): Stop mentioning lines
>> 	for "record function-call-history" and
>> 	"set record function-call-history-size".
>
>Would someone who knows what the software actually does review the
>text, please?  It's okay as far as Texinfo format and conventions go.

LGTM content-wise.

Markus.
Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928

RE: [PATCH] btrace, doc: Clarify record function-call-history documentation.

[Willgerodt, Felix]

>LGTM content-wise.
>
>Markus.

Thanks to both of you! Pushed.

I just realized that I forgot to add the ChangeLog entry to the actual file.
Sorry for that. I will push an "obvious" fixup patch shortly.

Felix

Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928