[python][rfc] Add "prototype" to docstrings of Frame-relatedfunctions and methods.

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

Hi,

A few functions and methods right now have a kind of prototype in the
docstring, which shows what arguments they expect (e.g., Value.string
and gdb.lookup_symbol). I think it would be helpful if all of the Python
API had them as well, so this patch adds them to the frame-related code.
I didn't push this yet. WDYT?

Also, since we're talking about documentation: currently in the user
manual we describe all "top-level" functions in the gdb module in the
"Basic Python" section, and class methods in their own section. This has
the disadvantage of putting related functionality in separate sections.
For example, the gdb.newest_frame function is documented in one place
and the Frame class is documented in another.

I suggest moving functions in the gdb module to the section to which
they relate, and keeping in Basic Python only functions which work in
isolation. WDYT?
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center

    
	* python/python-frame.c (frame_object_methods): Add "prototype" to
	docstrings of all methods.
	* python/python.c (GdbMethods): Add "prototype" to `frames',
	`newest_frame', `selected_frame', `frame_stop_reason_string' and
	`solib_address' entries.

diff --git a/gdb/python/python-frame.c b/gdb/python/python-frame.c
index ef1c178..f4458e1 100644
--- a/gdb/python/python-frame.c
+++ b/gdb/python/python-frame.c
@@ -600,26 +600,42 @@ gdbpy_initialize_frames (void)
 
 
 static PyMethodDef frame_object_methods[] = {
-  { "equals", frapy_equal_p, METH_VARARGS, "Compare frames." },
+  { "equals", frapy_equal_p, METH_VARARGS,
+    "equals (frame) -> Boolean.\n\
+Compare this frame to the given frame." },
   { "is_valid", frapy_is_valid, METH_NOARGS,
-    "Return true if this frame is valid, false if not." },
+    "is_valid () -> Boolean.\n\
+Return true if this frame is valid, false if not." },
   { "name", frapy_name, METH_NOARGS,
-    "Return the function name of the frame." },
-  { "type", frapy_type, METH_NOARGS, "Return the type of the frame." },
+    "name () -> String.\n\
+Return the function name of the frame, or None if it can't be determined." },
+  { "type", frapy_type, METH_NOARGS,
+    "type () -> Integer.\n\
+Return the type of the frame." },
   { "unwind_stop_reason", frapy_unwind_stop_reason, METH_NOARGS,
-    "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." },
+    "unwind_stop_reason () -> Integer.\n\
+Return the reason why it's not possible to find frames older than this." },
+  { "pc", frapy_pc, METH_NOARGS,
+    "pc () -> Long.\n\
+Return the frame's resume address." },
+  { "block", frapy_block, METH_NOARGS,
+    "block () -> gdb.Block.\n\
+Return the frame's code block." },
   { "addr_in_block", frapy_addr_in_block, METH_NOARGS,
-    "Return an address which falls within the frame's code block." },
+    "addr_in_block () -> Long.\n\
+Return an address which falls within the frame's code block." },
   { "older", frapy_older, METH_NOARGS,
-    "Return the frame immediately older (outer) to this frame." },
+    "older () -> gdb.Frame.\n\
+Return the frame immediately older (outer) to this frame." },
   { "newer", frapy_newer, METH_NOARGS,
-    "Return the frame immetidaely newer (inner) to this frame." },
+    "newer () -> gdb.Frame.\n\
+Return the frame immetidaely newer (inner) to this frame." },
   { "find_sal", frapy_find_sal, METH_NOARGS,
-    "Return the frame's symtab and line." },
+    "find_sal () -> gdb.Symtab_and_line.\n\
+Return the frame's symtab and line." },
   { "read_var_value", frapy_read_var_value, METH_VARARGS,
-    "Return the value of the variable in this frame." },
+    "read_var_value (variable) -> gdb.Value.\n\
+Return the value of the variable in this frame." },
   {NULL}  /* Sentinel */
 };
 
diff --git a/gdb/python/python.c b/gdb/python/python.c
index 20dfdd4..b95016a 100644
--- a/gdb/python/python.c
+++ b/gdb/python/python.c
@@ -1855,13 +1855,17 @@ static PyMethodDef GdbMethods[] =
     "Return a sequence of all loaded objfiles." },
 
   { "frames", gdbpy_frames, METH_NOARGS,
-    "Return a tuple of all frame objects." },
+    "frames () -> (gdb.Frame, ...).\n\
+Return a tuple of all frame objects." },
   { "newest_frame", gdbpy_newest_frame, METH_NOARGS,
-    "Return the newest frame object." },
+    "newest_frame () -> gdb.Frame.\n\
+Return the newest frame object." },
   { "selected_frame", gdbpy_selected_frame, METH_NOARGS,
-    "Return the selected frame object." },
-  { "frame_stop_reason_string", gdbpy_frame_stop_reason_string,
-    METH_VARARGS, "Return a string explaining unwind stop reason." },
+    "selected_frame () -> gdb.Frame.\n\
+Return the selected frame object." },
+  { "frame_stop_reason_string", gdbpy_frame_stop_reason_string, METH_VARARGS,
+    "stop_reason_string (Integer) -> String.\n\
+Return a string explaining unwind stop reason." },
 
   { "lookup_symbol", (PyCFunction) gdbpy_lookup_symbol,
     METH_VARARGS | METH_KEYWORDS,
@@ -1870,7 +1874,8 @@ Return a tuple with the symbol corresponding to the given name (or None) and\n\
 a boolean indicating if name is a field of the current implied argument\n\
 `this' (when the current language is object-oriented)." },
   { "solib_address", gdbpy_solib_address, METH_VARARGS,
-    "Return shared library holding a given address, or None." },
+    "solib_address (Long) -> String.\n\
+Return the name of the shared library holding a given address, or None." },
 
   { "find_pc_function", gdbpy_find_pc_function, METH_VARARGS,
     "Return the function containing the given pc value, or None." },