Re: [rfc] python API exposing inferior's frame stack.

[Eli Zaretskii <eliz@gnu.org>]

> From: Thiago Jung Bauermann <bauerman@br.ibm.com>
> Cc: gdb-patches@sourceware.org
> Date: Sun, 15 Mar 2009 13:11:06 -0300
> 
> El mar, 10-03-2009 a las 21:35 +0200, Eli Zaretskii escribió:
> > > 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.
> 
> Thanks for the review. The comments which I don't reply to below were
> addressed.
> 
> > > +@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?
> 
> I don't know, which direction is "higher in the call stack"? :-)
> 
> > Is "older" widespread enough to be self-explanatory?
> 
> "older" is the name of the Frame method used to get the previous frame
> (where "previous" is the convention used in the GDB source code), so it
> has a good chance of being clear to the user of the Python API. In any
> case, I reworded it to:
> 
> "Return an integer representing the reason why it's not possible to find
> frames older (outer) than this."

I prefer "frames previous to this one".  We already use similar
wording in frame_stop_reason_string.

> This usage directly reflects the way things are done in the GDB
> internals. Perhaps I should depart from it, remove gdb.find_pc_function
> and gdb.Frame.address_in_block and directly provide a gdb.Frame.function
> method which returns the gdb.Symbol object for the function
> corresponding to the frame?
> 
> It sounds like a better idea now that I think about it. But I'll have to
> post a patch exposing inferior symbols before I can submit it upstream.
> 
> I'll remove gdb.Frame.address_in_block for now, then.

Sounds good, thanks.

> > > +@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.
> 
> IMHO, "inner" and "outer" are already conforming to the terminology from
> the "Examining the Stack" chapter. It is a bit awkward to use "towards
> the outermost frame" to describe these methods, e.g.:
> 
> "Return the next frame in the direction towards the outermost frame."
> 
> and
> 
> "Return the next frame in the direction towards the innermost frame."
> 
> Mmm... Now that I tried, doesn't sound too bad. But still I find my
> original wording more direct and simpler to understand. What do you
> think?

We use "innermost" in the manual much more than "inner".  You can also
use "previous" and "next" if you like that better.

Also note that there's a typo in the quoted fragment ("immetidaely").

Thanks.