From 4a5a194ae8a871a781d4cdc73c7ba3ae7deafbaa Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Sat, 8 Sep 2018 09:39:41 -0600 Subject: [PATCH] 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 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/ChangeLog b/gdb/doc/ChangeLog index dfbb1540ba..a4971ce98f 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,9 @@ +2018-09-10 Tom Tromey + + PR python/23108: + * python.texi (Exception Handling): Rearrange gdb.GdbError text + and add a table. + 2018-09-10 Tom Tromey * gdb.texinfo (Compilation): Use "gcc", not "gcc.info", in @xref. diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 8c4dd8de66..59b6b3b72d 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.34.1