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

Eli Zaretskii
2005-03-26T10:40:10Z

> 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 [...].