Re: [PATCH 5/6] New MI command -trace-frame-collected

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 17 Jun 2013 18:12:09 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> On 06/14/2013 06:41 PM, Eli Zaretskii wrote:
> > This is not described anywhere in the manual.  In fact, the word
> > "wholly" never appears in the manual and "whole" never appears in any
> > context related to tracepoints.  In the node "Tracepoint Actions", we
> > don't make any distinction between collecting "in whole" and "in
> > part".
> > 
> > So if this distinction is important, please add to "Tracepoint
> > Actions" the explanation similar to what you wrote above, and then
> > make a cross-reference to that from the description of
> > -trace-frame-collected.
> 
> This distinction is important to the commands displaying contents in
> a given traceframe, such as -trace-frame-collected, but this distinction
> is not important to trace actions.

How can it not be important, when (AFAIU) the collection commands are
those that determine whether an object is collected in whole or only
partially?  By the time the user gets to displaying the collected
data, it's too late to decide about that.  Or am I missing something?

If I'm right, then it is important to describe this with tracepoint
actions because that is where the user needs to decide what to collect
and how.

On second thought, I still don't understand why is it so important to
emphasize this issue.  Isn't it trivially clear that in your example
myVar is collected in its entirety, while for myArray, only its
myIndex'th element is collected, and that the rest are expressions?
Why do we need to explain that?  Isn't it enough to say

  @item explicit-variables
  The set of objects that have been collected in their entirety (as
  opposed to collecting just a few elements of an array or a few struct
  members).

If this is good enough, then this paragraph:

> +This command returns the set of explicitly wholly collected (explained
> +below with an example) objects, register names, trace state variable
> +names, memory ranges and computed expressions that have been collected
> +at a particular trace frame.  The optional parameters to the command
> +affect the output format in different ways.  See the output description
> +table below for more details.

Needs to be rephrased to not mention the "explicitly wholly" thing.

> What do you think?

I don't like the result, sorry.

First, "explicitly wholly" sounds awkward, so much so that the reader
might decide this is a mistake of some kind.  Please use "collected
wholly" or "explicitly collected as a whole", if I didn't convince you
that the entire point about this is moot.

Second, this issue is too complicated to explain it with an example.
You need to provide rules by which the user will be able to decide
whether some data will be collected as a whole or not.

Third, you need @noindent here:

> +@smallexample
> +collect myVar, myArray[myIndex] myObj.field, myPtr->field, myCount + 2
> +collect *(int*)0xaf02bef0@@40
> +@end smallexample
> +the set of named objects explicitly wholly collected would be

after the "@end smallexample" line.

Thanks.