From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4792 invoked by alias); 10 Mar 2009 19:35:55 -0000 Received: (qmail 4784 invoked by uid 22791); 10 Mar 2009 19:35:54 -0000 X-SWARE-Spam-Status: No, hits=-0.5 required=5.0 tests=AWL,BARRACUDA_BRBL,BAYES_00,RCVD_IN_JMF_BR,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout6.012.net.il (HELO mtaout6.012.net.il) (84.95.2.16) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 10 Mar 2009 19:35:45 +0000 Received: from conversion-daemon.i-mtaout6.012.net.il by i-mtaout6.012.net.il (HyperSendmail v2007.08) id <0KGB00K0026XOX00@i-mtaout6.012.net.il> for gdb-patches@sourceware.org; Tue, 10 Mar 2009 21:36:25 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.228.183.217]) by i-mtaout6.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KGB0088X2GMG4A0@i-mtaout6.012.net.il>; Tue, 10 Mar 2009 21:36:23 +0200 (IST) Date: Tue, 10 Mar 2009 23:37:00 -0000 From: Eli Zaretskii Subject: Re: [rfc] python API exposing inferior's frame stack. In-reply-to: <1236706351.11106.17.camel@localhost.localdomain> To: Thiago Jung Bauermann Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: References: <1236706351.11106.17.camel@localhost.localdomain> 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: 2009-03/txt/msg00146.txt.bz2 > From: Thiago Jung Bauermann > Date: Tue, 10 Mar 2009 14:32:31 -0300 > > This patch allows a Python script to work with the inferior's frame > stack. For now, the only "entry point" for this API is the > gdb.selected_frame function. Thanks. I have a few comments about the documentation part of the patch. > +@tindex gdb.Frame > +@tindex Frame Please don't use @tindex, we don't use such an index in the GDB manual. > +When the debugged program stops, @value{GDBN} is able to analyse its call ^^^^^^^ "analyze", please. We use the US spelling. > If you try > +to use an invalid frame object, a @code{RuntimeError} exception will be > +thrown. Let's try to avoid unnecessary passive tense, as doing that makes the text more concise and easy to read: If you try to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError} exception. > +@findex gdb.selected_frame > +@defun selected_frame @defun automatically defines an entry in the index, so you don't need to have another @findex for it. > +@findex gdb.frame_stop_reason_string > +@defun frame_stop_reason_string @var{reason} Likewise. Also, no need to use @var in the @defun line to decorate arguments: @defun does that automatically for you. (You do need to use @var in the text that describes the function, such as below: > +Return a string explaining the reason why @value{GDBN} stopped unwinding > +frames, as expressed by the given @var{reason} code (an integer, see the > +@code{unwind_stop_reason} method further down in this section). > +@defmethod Frame equals @code{frame} "frame" is an argument, right? Then it again does not need any markup, certainly not @code. > All @code{gdb.Frame} methods will throw > +an exception if it is invalid at the time the method call is made. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ "at the time the method is called". > +Returns the type of the frame. The value can be one of ^^ Two spaces between sentences, please. > +@defmethod Frame unwind_stop_reason > +Return an integer representing the reason why it's not possible to find > +frames older than this. "older"? You mean, higher in the call stack? Is "older" widespread enough to be self-explanatory? > +@defmethod Frame address_in_block > +Returns an address which falls within the frame's code block. > +@end defmethod This is unclear to me. Is there only one such address? If not, why is that useful to get _an_ address? > +@defmethod Frame older > +Return the frame immediately older (outer) to this frame. > +@end defmethod > + > +@defmethod Frame newer > +Return the frame immetidaely newer (inner) to this frame. > +@end defmethod Suggest to use "higher" or "above" or "towards the outermost frame". Generally, try to use the terminology from the "Examining the Stack" chapter of the manual. > +@defmethod Frame read_var @var{variable} No need to use @var. > +Return the value of the given variable in this frame. @code{variable} must ^^^^^^^^^^^^^^^ @var{variable}.