Re: [MI tracepoints 9/9] documentation

[Eli Zaretskii <eliz at gnu dot org>]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Sun, 14 Mar 2010 12:04:11 +0300
> 
> I believe this documents all the changes made by my prior patches. OK?

Thanks.  A few comments:

>     MI tracepoints documentation.
>     
>     	gdb/doc/
>     	* gdb.texinfo (GDB/MI Tracepoint): Write it.

I'll probably get another cold shower for expressing opinions about
ChangeLog style, but I find this rather un-useful.  Why not

	* gdb.texinfo (GDB/MI Tracepoint): Document MI tracepoint
          commands.

i.e. without the header line?  Such short entries don't really need
any summary, they summarize themselves.

And btw, there's no node named "GDB/MI Tracepoint", you made changes
in more than one node with different names.

> +Create a tracepoint. @xref{Tracepoints}. When this parameter
                      ^^                  ^^
Two spaces between sentences, please (here and elsewhere).

> +@var{passcount}.  If breakpoint referred to by @var{tracepoint-number}
                        ^^^^^^^^^^
"the breakpoint"

> +tracepoints.  For detailed introduction, @pxref{Tracepoints}.

That's incorrect usage of @pxref (you should see 2 periods in the Info
output).  It should be used only in parentheses.  Please use "see
@ref" instead.

> +@smallexample
> + -trace-find @var{mode} [@var{parameters...}]
                                           ^^^
@dots{} will produce a nicer printed output here.  In any case, the
dots should be outside of @var{}.

> +modes and their parameters.  For details of operation, @pxref{tfind}.
                                                          ^^^^^^^^^^^^^
"see @ref".

> +@item pc
> +An integer address is required as parameter.

I think "An address is required as parameter", without the "integer"
part, is better.  An address is always integer in GDB, right?

> +next trace frame that corresponds to any tracepoint at the specified
> +address.
> +
> +@item pc-inside-range
> +Two integer addresses are required as parameters.

Ditto.

>                                                     Finds next trace
> +frame that corresponds to a tracepoint at an address inside the
> +specified range.

Inclusive or exclusive?

> +@item pc-outside-range
> +Two integer addresses are required as parameters.  Finds
> +next trace frame that corresponds to a tracepoint at an address outside
> +the specified range.

Ditto.

> +If the @samp{none} was passed as @var{mode}, the response does not
      ^^^
No need for "the" here.

> +@item traceframe
> +The index of the found traceframe.  This field is present iff
> +the @var{found} field has value of @samp{1}.

"found" should be in @samp, not @var: it is a literal string, not a
parameter that stands for some other string.

> +@item tracepoint
> +The index of the found tracepoint.  This field is present iff
> +the @var{found} field has value of @samp{1}.

Ditto.

> +See @xref{GDB/MI Frame Information} for description of this field.

Just "@xref" is enough, it produces "See" for you.

> +@smallexample
> + -trace-define-variable @var{name} [ @var{value} ]
> +@end smallexample
>  
> -@c @subheading -trace-list
> +Creates trace variable @var{name} if it does not exist.  If

"Create", to be consistent with the other descriptions ("find",
"return", etc.).

> +Return a table of all defined trace variables. Each element of the
> +table has the following fields

"fields:", with a colon.

> +signed integer.  This field may is absent iff current value is
                               ^^^
That "may" looks redundant.

> +@smallexample
> +(gdb)
> +-trace-list-variables
> +^done,trace-variables=@{nr_rows="1",nr_cols="3",
> +hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
> +     @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
> +     @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
> +body=[variable=@{name="$trace_timestamp",initial="0"@}
> +      variable=@{name="$foo",initial="10",current="15"@}]@}
> +(gdb)

?? This does not match the documentation: no "name", no "initial", no
"current"...  What am I missing?

> +@samp{-r} option, the data is download from the target and saved
                                 ^^^^^^^^
"downloaded", I think.

> +May have a value of either @samp{0}, when no tracing operations are
> +supported, @samp{1}, when all tracing operations are supported, and
> +@samp{file} when examining trace file.                          ^^^

"or" instead of "and", since you said "either" above.

> +                                                              The
> +value of @samp{request} mean the tracing was stopped as result of
                           ^^^^
"means"

> +@item stopping-tracepoint
> +The number of tracepoint which passcount as exceeded.
                            ^^^^^
"whose"

> +only present iff the @samp{stop-reason} field has the value of

You need either "only" or "iff", but not both.  If you leave "only",
make "iff" be just "if".

Okay with these changes.