* defs.h (return_to_top_level): Comment.

2 files changed, 19 insertions, 0 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 818d8eb..3d5e564 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,7 @@
+2001-11-19  Andrew Cagney  <ac131313@redhat.com>
+
+	* defs.h (return_to_top_level): Comment.
+
 Mon Nov 19 14:58:52 2001  Andrew Cagney  <cagney@redhat.com>
 
 	* remote.c (remote_open_1, remote_async_open_1): Use ISO C string
diff --git a/gdb/defs.h b/gdb/defs.h
index 390600f..e338f3c 100644
--- a/gdb/defs.h
+++ b/gdb/defs.h
@@ -1112,6 +1112,21 @@ enum return_reason
 #define RETURN_MASK_ALL		(RETURN_MASK_QUIT | RETURN_MASK_ERROR)
 typedef int return_mask;
 
+/* Throw an exception of type RETURN_REASON.  Will execute a LONG JUMP
+   to the inner most containing exception handler (established using
+   catch_exceptions() or the legacy catch_errors()).
+
+   Useful when a section of code that caught an exception finds it
+   needs to repropagate that exception up the call chain.
+
+   The name return_to_top_level() dates back to a time when GDB had
+   only one exception handler installed at the top level.  This really
+   did return to the top level.  The name should probably be changed.
+
+   NOTE: Some sections of code are using error_begin() in conjunction
+   with return_to_top_level() to throw the initial exception.  That
+   code should, instead, use either error() or error_string().  */
+
 extern NORETURN void return_to_top_level (enum return_reason) ATTR_NORETURN;
 
 /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception