Re: [RFC] Refactor doc on stop notification.

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 28 Dec 2012 10:52:04 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> >> >+If the stub receives a @var{ack} packet and there are no
> >> >+additional stop events to report, the stub shall return an @samp{OK}
> >> >+response.  At this point, @value{GDBN} has finished processing a
> >> >+notification and the stub has completed sending any queued events.
> >> >+@value{GDBN} ignores additional notifications received before this
> >> >+point.       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > "Before" or "after"?  If "before" is correct, then I don't think I
> > understand what this paragraph wants to tell.
> >
> 
> It is "before".  At point [1], GDB has finished processing %Stop.  GDB 
> will ignore any %Stop notifications (in [2]), *before* point [1].
> 
> <- %Stop:T0505:XXXX;
> ....
> -> vStopped
> <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
> -> vStopped
> <- %Stop:T0505:XXXX; [2]
> <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
> -> vStopped
> <- OK
>   [1]
> 
> This paragraph is to tell that point [1] is the end of a processing to a 
> notification.  After this point, GDB is ready again to process 
> notification, and before this point, GDB ignore notifications.

But the whole process, between the first "%Stop:T0505:XXXX;" and "OK"
is also called "notifications".  That's where the confusion comes
from.  If you want to tell that any _new_ notifications cannot be
_started_ until the final "OK" is received, then please say that in
these very words.

> >> >+The process of asynchronous notification can be illustrated by the
> >> >+following example:
> >> >+@smallexample
> >> >+<- @code{%name:event}
> >> >+@code{...}
> >> >+-> @code{ack}
> >> >+<- @code{event}
> >> >+-> @code{ack}
> >> >+<- @code{event}
> >> >+-> @code{ack}
> >> >+<- @code{OK}
> >> >+@end smallexample
> > I would suggest to consider putting here a real example, like the one
> > you used to explain the issue to me.
> 
> My intention here is to add a template or a pattern for a given new 
> notification, comprised of name, event and ack, to describe how rsp 
> traffic looks like for notification in general.  IMO, it is more 
> informative than a specific notification.

How about _adding_ an example, without removing the template?