Re: [mi] organize possible exec async mi oc command reasons

["Eli Zaretskii" <eliz@gnu.org>]

> Date: Thu, 24 Mar 2005 16:02:31 -0500
> From: Bob Rossi <bob@brasko.net>
> Cc: gdb-patches@sources.redhat.com
> 
> >     +The following lists the current set of reasons why @sc{gdb/mi} would
> >     +return with *stopped (exec-async-output).  
> > What does this sentence mean? and why there's a `*' before "stopped"?
> > and what's with the "exec-async-output" inside parens?
> > 
> 
> How about I replace that with this, 
> 
> The following enumerates the current set of reasons why @sc{gdb/mi} would
> return with an @var{exec-async-output} command.

This still doesn't look right: if exec-async-output is in @var, it
should stand for something.  Do I understand correctly that it stands
for one of these:

    breakpoint-hit
    watchpoint-trigger
    read-watchpoint-trigger
    access-watchpoint-trigger
    function-finished
    location-reached
    watchpoint-scope
    end-stepping-range
    exited-signalled
    exited
    exited-normally
    signal-received

?  If so, then you should modify the @table with "stopped" like this:

    @table @code
    @item *stopped @var{reason}
    @end table

and then list the possible values for @var{reason}, see below.

Also, these are not commands, so it's wrong to say ``GDB/MI would
return with an EXEC-ASYNC-OUTPUT command''.  You should say something
like

    The following enumerates the current set of possible values for
    @var{reason}.

or, better yet

    @var{reason} can be one of the following:

> >     +A breakpoint was reached, "breakpoint-hit"
> > 
> > This is not an English sentence, AFAIU.
> 
> The list is suppossed to be all of the reasons why GDB would return an
> exec async output command to the FE.
> 
> The first part of each item is a description of why GDB returned, the
> second part is the actual reason GDB/MI will give. 
> (ie "reason=breakpoint-hit").

Then you should use @table, like this:

    @table @code
    @item breakpoint-hit
    A breakpoint was reached.
    @item watchpoint-trigger
    A watchpoint was triggered.
    ...
    @end table

Btw, do we always have @var{reason} after "stopped"?  If not, then
it's optional and should be inside [...].