From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10774 invoked by alias); 14 Mar 2010 18:25:59 -0000 Received: (qmail 10766 invoked by uid 22791); 14 Mar 2010 18:25:58 -0000 X-SWARE-Spam-Status: No, hits=-1.3 required=5.0 tests=AWL,BAYES_00,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout22.012.net.il (HELO mtaout22.012.net.il) (80.179.55.172) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sun, 14 Mar 2010 18:25:52 +0000 Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0KZA00900AZEDB00@a-mtaout22.012.net.il> for gdb-patches@sourceware.org; Sun, 14 Mar 2010 20:25:25 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.229.173.249]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KZA002NVB6BUDF0@a-mtaout22.012.net.il>; Sun, 14 Mar 2010 20:25:25 +0200 (IST) Date: Sun, 14 Mar 2010 18:25:00 -0000 From: Eli Zaretskii Subject: Re: [MI tracepoints 9/9] documentation In-reply-to: <201003141204.12015.vladimir@codesourcery.com> To: Vladimir Prus Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83k4te221u.fsf@gnu.org> References: <201003141204.12015.vladimir@codesourcery.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-03/txt/msg00500.txt.bz2 > From: Vladimir Prus > 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.