Re: [PATCH 3/3] doc, record: document record changes

[Eli Zaretskii <eliz at gnu dot org>]

> From: "Metzger, Markus T" <markus.t.metzger@intel.com>
> CC: "jan.kratochvil@redhat.com" <jan.kratochvil@redhat.com>,
> 	"gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> Date: Fri, 1 Mar 2013 14:06:23 +0000
> 
> > > +"record function-call-history" prints the names of the functions
> > > +from instructions stored in the execution log.
> > 
> > "prints the names of the functions called by instructions in the
> > execution log"
> 
> I'm not sure whether "called" is the right term. The algorithm walks over
> all instructions and collects the functions from which these instructions
> originated.
> 
> Example:
> 
> 1  void foo (void)
> 2 {
> 3    ...
> 4    bar ();
> 5    ...
> 6  }
> 
> When we record the execution of foo, there will be instructions for the
> first ..., then instructions for bar, and then instructions for the second ....
> 
> The "record function-call-history" will print:
>   foo.c:1-4	foo (void)
>   bar.c:8-12	bar (void)
>   foo.c:5-6	foo (void

This indicates that "record function-execution-history" might be a
better name.  But in any case, weren't 'bar' and 'foo' called in this
example?

Your original text, "prints the names of the functions from
instructions", is confusing, since instructions don't store function
names, they store addresses and numbers.

> > > +@kindex show record full memory-query
> > > +@item show record full memory-query
> > 
> > I think it is good enough to have only one "@kindex set record" and
> > one "@kindex show record" entry (which you already have at the
> > beginning of this description), without the entries that advertise the
> > rest of the command arguments.  These varieties are all described
> > together, so the multitude of index entries does not have any useful
> > effect, it just bloats the index.
> 
> I just renamed the text for existing indices. Do you still want me to
> merge them?

Can you give one example of such renaming?  I'm not sure I understand
what you did.

> > > +@item record function-call-history
> > > +Print function names for instructions stored in the recorded execution
> > > +log.  Prints one line for each sequence of instructions that is
> > > +correlated to the same function.
> > 
> > Isn't the last sentence equivalent to saying
> > 
> >   Prints one line for each function call in the execution log.
> > 
> > ?  If it is equivalent, I think my suggested wording is more clear and
> > less technical.
> 
> See above.

Given the example (which I think it would be good to have in the
manual), I suggest this wording instead:

  Prints one line for each sequence of instructions that all belong to
  the same function.