Re: [RFC] Refactor doc on stop notification.

[Yao Qi <yao@codesourcery.com>]

On 12/28/2012 02:09 AM, Eli Zaretskii wrote:
>> +Otherwise, @value{GDBN} must be prepared to receive a
> I would delete the "Otherwise" part.  I don't think it adds anything
> to the text.
>

OK, I remove the first sentence, and keep the rest of paragraph, as it 
expresses that "when the notification may come in".

>> >+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.

>> >+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.

The word "example" may be misleading, how about this below?

The process of asynchronous notification can be illustrated by the
following template:
@smallexample
<- @code{%name:event}
@code{...}
-> @code{ack}
<- @code{event}
-> @code{ack}
<- @code{event}
-> @code{ack}
<- @code{OK}
@end smallexample
The asynchronous notification should define its @var{name},
@var{event} and @var{ack}.

-- 
Yao (齐尧)