[python] Move doc of frame-related functions to the Frames InPython section.

[Thiago Jung Bauermann <bauerman at br dot ibm dot com>]

Hi,

This patch moves the frame-related functions from the Basic Python to
the Frames In Python section. I'll move the other functions in Basic
Python later.

Committed.
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center


commit fae8e4264ad99439cba03d572f38d73e495c88da
Author: Thiago Jung Bauermann <bauerman@br.ibm.com>
Date:   Tue Mar 3 11:51:17 2009 -0300

    Move doc of frame-related functions to the Frames In Python section.
    
    Plus other small doc cleanups.
    
    gdb/
    	* python/python.c (GdbMethods): Slight change of wording in doc
    	string for the `frames' entry.
    
    gdb/doc/
    	* gdb.texinfo (Basic Python): Move frame-related functions from
    	here ...
    	(Frames In Python): ... to here.  Update (commented) reference
    	in Frame.block and Frame.find_sal to use @pxref instead of
    	@xref.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f22f931..382f0c1 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18250,29 +18250,6 @@ Flush @value{GDBN}'s paginated standard output stream.  Flushing
 function.
 @end defun
 
-@findex gdb.frames
-@defun frames
-Return a tuple of all frame objects.
-@end defun
-
-@findex gdb.newest_frame
-@defun newest_frame
-Return the newest frame object.
-@end defun
-
-@findex gdb.selected_frame
-@defun selected_frame
-Return the selected frame object.
-@end defun
-
-@findex gdb.frame_stop_reason_string
-@defun frame_stop_reason_string @var{reason}
-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 in
-@xref{Frames In Python,,Accessing inferior stack frames from Python}.)
-@end defun
-
 @findex gdb.read_memory
 @defun read_memory @var{address} @var{length}
 Read @var{length} bytes of memory from the inferior, starting at @var{address}.
@@ -19492,12 +19469,34 @@ separated by newlines.  If there are no commands, this attribute is
 @tindex Frame
 When the debugged program stops, @value{GDBN} is able to analyse its call
 stack (@pxref{Frames,,Stack frames}).  The @code{gdb.Frame} class
-represents a frame in the stack.  You can get a tuple containing all the
-frames in the stack with the @code{gdb.frames} function, the newest
-frame with the @code{gdb.newest_frame} function, and the selected frame
-with the @code{gdb.selected_frame} function
-(see @xref{Selection,,Selecting a Frame}.)  See
-@xref{Basic Python,,Basic Python}.
+represents a frame in the stack.  A @code{gdb.Frame} object is only valid
+while its corresponding frame exists in the inferior's stack.  If you try
+to use an invalid frame object, a @code{RuntimeError} exception will be
+thrown.
+
+The following frame-related functions are available in the @code{gdb} module:
+
+@findex gdb.frames
+@defun frames
+Return a tuple containing all frame objects.
+@end defun
+
+@findex gdb.newest_frame
+@defun newest_frame
+Return the newest frame object.
+@end defun
+
+@findex gdb.selected_frame
+@defun selected_frame
+Return the selected frame object.  (@pxref{Selection,,Selecting a Frame}).
+@end defun
+
+@findex gdb.frame_stop_reason_string
+@defun frame_stop_reason_string @var{reason}
+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).
+@end defun
 
 A @code{gdb.Frame} object has the following methods:
 
@@ -19535,7 +19534,7 @@ Returns the frame's resume address.
 @end defmethod
 
 @defmethod Frame block
-Returns the frame's code block. @c (see @xref{Block,,Code Blocks and Scopes}).
+Returns the frame's code block. @c (@pxref{Block,,Code Blocks and Scopes}).
 @end defmethod
 
 @defmethod Frame address_in_block
@@ -19551,7 +19550,7 @@ Return the frame immediately newer (inner) to this frame.
 @end defmethod
 
 @defmethod Frame find_sal
-Return the frame's symtab and line object. @c (see @xref{Symtab_and_line,, Symtab and line}).
+Return the frame's symtab and line object. @c (@pxref{Symtab_and_line,, Symtab and line}).
 @end defmethod
 
 @defmethod Frame read_var @var{variable}
diff --git a/gdb/python/python.c b/gdb/python/python.c
index d751fd4..c15e718 100644
--- a/gdb/python/python.c
+++ b/gdb/python/python.c
@@ -1876,7 +1876,7 @@ static PyMethodDef GdbMethods[] =
 
   { "frames", gdbpy_frames, METH_NOARGS,
     "frames () -> (gdb.Frame, ...).\n\
-Return a tuple of all frame objects." },
+Return a tuple containing all frame objects." },
   { "newest_frame", gdbpy_newest_frame, METH_NOARGS,
     "newest_frame () -> gdb.Frame.\n\
 Return the newest frame object." },