This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[PATCH 06/14] Reword gdb.GdbError text
- From: Tom Tromey <tom at tromey dot com>
- To: gdb-patches at sourceware dot org
- Cc: Tom Tromey <tom at tromey dot com>
- Date: Sat, 8 Sep 2018 14:14:09 -0600
- Subject: [PATCH 06/14] Reword gdb.GdbError text
- References: <20180908201417.13444-1-tom@tromey.com>
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-08 Tom Tromey <tom@tromey.com>
PR python/23108:
* python.texi (Exception Handling): Rearrange gdb.GdbError text
and add a table.
---
gdb/doc/ChangeLog | 6 ++++++
gdb/doc/python.texi | 21 +++++++++++++++------
2 files changed, 21 insertions(+), 6 deletions(-)
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
--
2.13.6