From: Tom Tromey <tom@tromey.com>
Date: Sat, 8 Sep 2018 15:39:41 +0000 (-0600)
Subject: Reword gdb.GdbError text
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=4a5a194ae8a871a781d4cdc73c7ba3ae7deafbaa;p=binutils-gdb.git

Reword gdb.GdbError text

PR python/23108 points out that the gdb.GdbError documentation is
somewhat difficult to find.  The exception is apparently just
mentioned in passing.  This patch introduces a new table and adds a
bit more text to try to make it more obvious.

gdb/doc/ChangeLog
2018-09-10  Tom Tromey  <tom@tromey.com>

	PR python/23108:
	* python.texi (Exception Handling): Rearrange gdb.GdbError text
	and add a table.
---

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index dfbb1540ba1..a4971ce98f3 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2018-09-10  Tom Tromey  <tom@tromey.com>
+
+	PR python/23108:
+	* python.texi (Exception Handling): Rearrange gdb.GdbError text
+	and add a table.
+
 2018-09-10  Tom Tromey  <tom@tromey.com>
 
 	* gdb.texinfo (Compilation): Use "gcc", not "gcc.info", in @xref.
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 8c4dd8de669..59b6b3b72db 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -528,12 +528,20 @@ message as its value and the Python call stack backtrace at the Python
 statement closest to where the @value{GDBN} error occured as the
 traceback.
 
-@findex gdb.GdbError
-When implementing @value{GDBN} commands in Python via @code{gdb.Command},
-it is useful to be able to throw an exception that doesn't cause a
-traceback to be printed.  For example, the user may have invoked the
-command incorrectly.  Use the @code{gdb.GdbError} exception
-to handle this case.  Example:
+
+When implementing @value{GDBN} commands in Python via
+@code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
+to be able to throw an exception that doesn't cause a traceback to be
+printed.  For example, the user may have invoked the command
+incorrectly.  @value{GDBN} provides a special exception class that can
+be used for this purpose.
+
+@ftable @code
+@item gdb.GdbError
+When thrown from a command or function, this exception will cause the
+command or function to fail, but the Python stack will not be
+displayed.  @value{GDBN} does not throw this exception itself, but
+rather recognizes it when thrown from user Python code.  Example:
 
 @smallexample
 (gdb) python
@@ -551,6 +559,7 @@ to handle this case.  Example:
 (gdb) hello-world 42
 hello-world takes no arguments
 @end smallexample
+@end ftable
 
 @node Values From Inferior
 @subsubsection Values From Inferior