Re: [PATCH] traceframe_changed observer and MI notification

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 18 Sep 2012 08:08:18 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: Eli Zaretskii <eliz@gnu.org>
> 
> On 08/31/2012 05:09 PM, Yao Qi wrote:
> > gdb/doc:
> >
> > 	* observer.texi (GDB Observers): New observer 'traceframe_changed'.
> > 	* gdb.texinfo (GDB/MI Async Records): Mention new MI notification
> > 	'=traceframe-changed'.
> 
> Eli,
> Could you review the doc part of this patch? 
> http://sourceware.org/ml/gdb-patches/2012-08/msg00885.html

Sorry about the delay.  Here goes:

> +@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum}
> +@itemx =traceframe-changed,end
> +Reports that the traceframe is changed and its number is @var{tfnum}.

I suggest to reword:

  Reports that the trace frame was changed, and its new number is @var{tfnum}.

> +or @value{GDBN} stops examining traceframes and resumes live debugging.

This line should be edited to explain the meaning of negative values
of tfnum.

> +The number of the tracepoint associated with this traceframe is
> +@var{tpnum}.                                      ^^^^^^^^^^

"trace frame"

> +@deftypefun void traceframe_changed (int @var{tfnum}, int @var{tpnum})
> +The traceframe is changed to @var{tfnum} in command @code{tfind}.
       ^^^^^^^^^^
"trace frame"

Also, I don't understand the significance of the reference to
'tfind'.  Why is it important to mention that?

> +The number of the tracepoint associated with this traceframe is
> +@var{tpnum}.  When @var{tfnum} is negative, @value{GDBN} resumes
> +live debugging.

The last sentence should follow the description of tfnum.  I would
also rephrase it:

 If var{tfnum} is negative, it means @value{GDBN} resumes live debugging.

Thanks.