[python] Add comments to gdb.Frame-related functions, and minordocstring fixes.

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

Hi,

This patch makes some minor tidying up of the frame api code. Committed.

	* python/python-frame.c: Fix copyright.
	Add comments describing frapy_* and gdbpy_* functions.
	(frame_object_methods): Fix description of `unwind_stop_reason' entry.
	* python/python.c (GdbMethods): Add period to description of `frames',
	`newest_frame', `selected_frame' and `frame_stop_reason_string' entries.
---
 gdb/python/python-frame.c |   69 +++++++++++++++++++++++++++++++++++++++++++-
 gdb/python/python.c       |    8 ++--
 2 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/gdb/python/python-frame.c b/gdb/python/python-frame.c
index c468305..e5b640c 100644
--- a/gdb/python/python-frame.c
+++ b/gdb/python/python-frame.c
@@ -1,6 +1,6 @@
 /* Python interface to stack frames
 
-   Copyright (C) 2008 Free Software Foundation, Inc.
+   Copyright (C) 2008, 2009 Free Software Foundation, Inc.
 
    This file is part of GDB.
 
@@ -54,6 +54,9 @@ typedef struct {
 
 static PyTypeObject frame_object_type;
 
+/* Returns the frame_info object corresponding to the given Python Frame
+   object.  If the frame doesn't exist anymore (the frame id doesn't
+   correspond to any frame in the inferior), returns NULL.  */
 
 static struct frame_info *
 frame_object_to_frame_info (frame_object *frame_obj)
@@ -70,6 +73,9 @@ frame_object_to_frame_info (frame_object *frame_obj)
   return frame;
 }
 
+/* Called by the Python interpreter to obtain string representation
+   of the object.  */
+
 static PyObject *
 frapy_str (PyObject *self)
 {
@@ -87,6 +93,10 @@ frapy_str (PyObject *self)
   return result;
 }
 
+/* Implementation of gdb.Frame.is_valid (self) -> Boolean.
+   Returns True if the frame corresponding to the frame_id of this
+   object still exists in the inferior.  */
+
 static PyObject *
 frapy_is_valid (PyObject *self, PyObject *args)
 {
@@ -99,6 +109,8 @@ frapy_is_valid (PyObject *self, PyObject *args)
   Py_RETURN_TRUE;
 }
 
+/* Implementation of gdb.Frame.equals (self, other) -> Boolean. */
+
 static PyObject *
 frapy_equal_p (PyObject *self, PyObject *args)
 {
@@ -122,6 +134,9 @@ frapy_equal_p (PyObject *self, PyObject *args)
   Py_RETURN_FALSE;
 }
 
+/* Implementation of gdb.Frame.name (self) -> String.
+   Returns the name of the function corresponding to this frame.  */
+
 static PyObject *
 frapy_name (PyObject *self, PyObject *args)
 {
@@ -150,6 +165,9 @@ frapy_name (PyObject *self, PyObject *args)
   return result;
 }
 
+/* Implementation of gdb.Frame.type (self) -> Integer.
+   Returns the frame type, namely one of the gdb.*_FRAME constants.  */
+
 static PyObject *
 frapy_type (PyObject *self, PyObject *args)
 {
@@ -168,6 +186,9 @@ frapy_type (PyObject *self, PyObject *args)
   return PyInt_FromLong (type);
 }
 
+/* Implementation of gdb.Frame.unwind_stop_reason (self) -> Integer.
+   Returns one of the gdb.FRAME_UNWIND_* constants.  */
+
 static PyObject *
 frapy_unwind_stop_reason (PyObject *self, PyObject *args)
 {
@@ -186,6 +207,10 @@ frapy_unwind_stop_reason (PyObject *self, PyObject *args)
   return PyInt_FromLong (stop_reason);
 }
 
+
+/* Implementation of gdb.Frame.pc (self) -> Long.
+   Returns the frame's resume address.  */
+
 static PyObject *
 frapy_pc (PyObject *self, PyObject *args)
 {
@@ -204,6 +229,9 @@ frapy_pc (PyObject *self, PyObject *args)
   return PyLong_FromUnsignedLongLong (pc);
 }
 
+/* Implementation of gdb.Frame.block (self) -> gdb.Block.
+   Returns the frame's code block.  */
+
 static PyObject *
 frapy_block (PyObject *self, PyObject *args)
 {
@@ -225,6 +253,10 @@ frapy_block (PyObject *self, PyObject *args)
   Py_RETURN_NONE;
 }
 
+
+/* Implementation of gdb.Frame.addr_in_block (self) -> Long.
+   Returns an address which falls within the frame's code block.  */
+
 static PyObject *
 frapy_addr_in_block (PyObject *self, PyObject *args)
 {
@@ -243,6 +275,9 @@ frapy_addr_in_block (PyObject *self, PyObject *args)
   return PyLong_FromUnsignedLongLong (pc);
 }
 
+/* Convert a frame_info struct to a Python Frame object.
+   Sets a Python exception and returns NULL on error.  */
+
 static frame_object *
 frame_info_to_frame_object (struct frame_info *frame)
 {
@@ -276,6 +311,10 @@ frame_info_to_frame_object (struct frame_info *frame)
   return frame_obj;
 }
 
+/* Implementation of gdb.Frame.older (self) -> gdb.Frame.
+   Returns the frame immediately older (outer) to this frame, or None if
+   there isn't one.  */
+
 static PyObject *
 frapy_older (PyObject *self, PyObject *args)
 {
@@ -301,6 +340,10 @@ frapy_older (PyObject *self, PyObject *args)
   return prev_obj;
 }
 
+/* Implementation of gdb.Frame.newer (self) -> gdb.Frame.
+   Returns the frame immediately newer (inner) to this frame, or None if
+   there isn't one.  */
+
 static PyObject *
 frapy_newer (PyObject *self, PyObject *args)
 {
@@ -326,6 +369,9 @@ frapy_newer (PyObject *self, PyObject *args)
   return next_obj;
 }
 
+/* Implementation of gdb.Frame.find_sal (self) -> Symtab_and_line.
+   Returns the frame's symtab and line.  */
+
 static PyObject *
 frapy_find_sal (PyObject *self, PyObject *args)
 {
@@ -346,6 +392,11 @@ frapy_find_sal (PyObject *self, PyObject *args)
   return sal_obj;
 }
 
+/* Implementation of gdb.Frame.read_var_value (self, variable) -> gdb.Value.
+   Returns the value of the given variable in this frame.  The argument can be
+   either a gdb.Symbol or a string.  Returns None if GDB can't find the
+   specified variable.  */
+
 static PyObject *
 frapy_read_var_value (PyObject *self, PyObject *args)
 {
@@ -399,6 +450,9 @@ frapy_read_var_value (PyObject *self, PyObject *args)
   Py_RETURN_NONE;
 }
 
+/* Implementation of gdb.frames () -> ( gdb.Frame, ... ).
+   Returns a tuple of all frame objects.  */
+
 PyObject *
 gdbpy_frames (PyObject *self, PyObject *args)
 {
@@ -449,6 +503,9 @@ gdbpy_frames (PyObject *self, PyObject *args)
   return tuple;
 }
 
+/* Implementation of gdb.newest_frame () -> gdb.Frame.
+   Returns the newest frame object.  */
+
 PyObject *
 gdbpy_newest_frame (PyObject *self, PyObject *args)
 {
@@ -466,6 +523,9 @@ gdbpy_newest_frame (PyObject *self, PyObject *args)
   return (PyObject *) frame_obj;
 }
 
+/* Implementation of gdb.selected_frame () -> gdb.Frame.
+   Returns the selected frame object.  */
+
 PyObject *
 gdbpy_selected_frame (PyObject *self, PyObject *args)
 {
@@ -483,6 +543,9 @@ gdbpy_selected_frame (PyObject *self, PyObject *args)
   return (PyObject *) frame_obj;
 }
 
+/* Implementation of gdb.newest_frame (Integer) -> String.
+   Return a string explaining the unwind stop reason.  */
+
 PyObject *
 gdbpy_frame_stop_reason_string (PyObject *self, PyObject *args)
 {
@@ -502,6 +565,8 @@ gdbpy_frame_stop_reason_string (PyObject *self, PyObject *args)
   return PyUnicode_Decode (str, strlen (str), host_charset (), NULL);
 }
 
+/* Sets up the Frame API in the gdb module.  */
+
 void
 gdbpy_initialize_frames (void)
 {
@@ -543,7 +608,7 @@ static PyMethodDef frame_object_methods[] = {
     "Return the function name of the frame." },
   { "type", frapy_type, METH_NOARGS, "Return the type of the frame." },
   { "unwind_stop_reason", frapy_unwind_stop_reason, METH_NOARGS,
-    "Return the function name of the frame." },
+    "Return the reason why it's not possible to find frames older than this." },
   { "pc", frapy_pc, METH_NOARGS, "Return the frame's resume address." },
   { "block", frapy_block, METH_NOARGS, "Return the frame's code block." },
   { "addr_in_block", frapy_addr_in_block, METH_NOARGS,
diff --git a/gdb/python/python.c b/gdb/python/python.c
index c9f2231..63d3282 100644
--- a/gdb/python/python.c
+++ b/gdb/python/python.c
@@ -1851,13 +1851,13 @@ static PyMethodDef GdbMethods[] =
     "Return a sequence of all loaded objfiles." },
 
   { "frames", gdbpy_frames, METH_NOARGS,
-    "Return a tuple of all frame objects" },
+    "Return a tuple of all frame objects." },
   { "newest_frame", gdbpy_newest_frame, METH_NOARGS,
-    "Return the newest frame object" },
+    "Return the newest frame object." },
   { "selected_frame", gdbpy_selected_frame, METH_NOARGS,
-    "Return the selected frame object" },
+    "Return the selected frame object." },
   { "frame_stop_reason_string", gdbpy_frame_stop_reason_string,
-    METH_VARARGS, "Return a string explaining unwind stop reason" },
+    METH_VARARGS, "Return a string explaining unwind stop reason." },
 
   { "lookup_symbol", (PyCFunction) gdbpy_lookup_symbol,
     METH_VARARGS | METH_KEYWORDS,
-- 
1.5.6.5