From: Andrew Burgess <andrew.burgess@embecosm.com>
Date: Thu, 18 Mar 2021 16:44:14 +0000 (+0000)
Subject: gdb/doc: fix the example for get_set_string in Python API docs
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=763b8efdcc0ab0f94f7af48792eb5c97b6eca41b;p=binutils-gdb.git

gdb/doc: fix the example for get_set_string in Python API docs

The small example for gdb.Parameter.get_set_string does not return a
string.  The documentation is very clear that this method must return
a string, and indeed, inspecting the code in gdb/python/py-param.c
shows that a string return value is required (if an exception is not
thrown).

While inspecting the code in gdb/python/py-param.c I noticed that the
comment for the C++ code that invokes the Python get_set_string method
is wrong, so I updated that too.

gdb/ChangeLog:

	* python/py-param.c (get_set_value): Update header comment.

gdb/doc/ChangeLog:

	* python.texinfo (Parameters In Python): Return empty string in
	small example code.
---

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index a606f54009c..09cfe0f6723 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,7 @@
+2021-03-18  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* python/py-param.c (get_set_value): Update header comment.
+
 2021-03-17  Simon Marchi  <simon.marchi@polymtl.ca>
 
 	* infrun.c (check_multi_target_resumption): Remove argument to
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index add31a0cc39..625aa29728d 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2021-03-18  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* python.texinfo (Parameters In Python): Return empty string in
+	small example code.
+
 2021-02-24  Andrew Burgess  <andrew.burgess@embecosm.com>
 
 	* gdb.texinfo (Files): Document new 'maint info target-sections'
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index ba3d2f92a43..9135d415dd1 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4041,6 +4041,7 @@ class ExampleParam (gdb.Parameter):
         self.value = self.saved_value
         raise gdb.GdbError('Failed to validate')
       self.saved_value = self.value
+      return ""
 @end smallexample
 @end defun
 
diff --git a/gdb/python/py-param.c b/gdb/python/py-param.c
index 49819ce4f10..ab9e883dc2d 100644
--- a/gdb/python/py-param.c
+++ b/gdb/python/py-param.c
@@ -368,11 +368,10 @@ call_doc_function (PyObject *obj, PyObject *method, PyObject *arg)
 }
 
 /* A callback function that is registered against the respective
-   add_setshow_* set_doc prototype.  This function will either call
-   the Python function "get_set_string" or extract the Python
-   attribute "set_doc" and return the contents as a string.  If
-   neither exist, insert a string indicating the Parameter is not
-   documented.  */
+   add_setshow_* set_doc prototype.  This function calls the Python function
+   "get_set_string" if it exists, which will return a string.  That string
+   is then printed.  If "get_set_string" does not exist, or returns an
+   empty string, then nothing is printed.  */
 static void
 get_set_value (const char *args, int from_tty,
 	       struct cmd_list_element *c)