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

[Eli Zaretskii <eliz at gnu dot org>]

> From: Thiago Jung Bauermann <bauerman@br.ibm.com>
> 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}.