* exceptions.h: Clean up some comments on catch_exceptions usage.

* exceptions.c: Ditto.  Plus mark catch_errors as superseded by
	catch_exceptions.

gdb/ChangeLog

@@ -1,3 +1,9 @@
+2009-03-13  Doug Evans  <dje@google.com>
+
+	* exceptions.h: Clean up some comments on catch_exceptions usage.
+	* exceptions.c: Ditto.  Plus mark catch_errors as superseded by
+	catch_exceptions.
+
 2009-02-17  Joel Brobecker  <brobecker@adacore.com>
 
 	The following patch helps getting rid of a warning inside solib-som.c.

gdb/exceptions.c

@@ -417,25 +417,21 @@ throw_error (enum errors error, const char *fmt, ...)
   va_end (args);
 }
 
-/* Call FUNC() with args FUNC_UIOUT and FUNC_ARGS, catching any
-   errors.  Set FUNC_CAUGHT to an ``enum return_reason'' if the
-   function is aborted (using throw_exception() or zero if the
-   function returns normally.  Set FUNC_VAL to the value returned by
-   the function or 0 if the function was aborted.
+/* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception
+   handler.  If an exception (enum return_reason) is thrown using
+   throw_exception() than all cleanups installed since
+   catch_exceptions() was entered are invoked, the (-ve) exception
+   value is then returned by catch_exceptions.  If FUNC() returns
+   normally (with a positive or zero return value) then that value is
+   returned by catch_exceptions().  It is an internal_error() for
+   FUNC() to return a negative value.
+
+   See exceptions.h for further usage details.
 
    Must not be called with immediate_quit in effect (bad things might
    happen, say we got a signal in the middle of a memcpy to quit_return).
    This is an OK restriction; with very few exceptions immediate_quit can
-   be replaced by judicious use of QUIT.
-
-   MASK specifies what to catch; it is normally set to
-   RETURN_MASK_ALL, if for no other reason than that the code which
-   calls catch_errors might not be set up to deal with a quit which
-   isn't caught.  But if the code can deal with it, it generally
-   should be RETURN_MASK_ERROR, unless for some reason it is more
-   useful to abort only the portion of the operation inside the
-   catch_errors.  Note that quit should return to the command line
-   fairly quickly, even if some further processing is being done.  */
+   be replaced by judicious use of QUIT.  */
 
 /* MAYBE: cagney/1999-11-05: catch_errors() in conjunction with
    error() et.al. could maintain a set of flags that indicate the the
@@ -445,10 +441,6 @@ throw_error (enum errors error, const char *fmt, ...)
    code also randomly used a SET_TOP_LEVEL macro that directly
    initialize the longjmp buffers. */
 
-/* MAYBE: cagney/1999-11-05: Should the catch_errors and cleanups code
-   be consolidated into a single file instead of being distributed
-   between utils.c and top.c? */
-
 int
 catch_exceptions (struct ui_out *uiout,
 		  catch_exceptions_ftype *func,
@@ -505,6 +497,8 @@ catch_exceptions_with_msg (struct ui_out *uiout,
   return val;
 }
 
+/* This function is superseded by catch_exceptions().  */
+
 int
 catch_errors (catch_errors_ftype *func, void *func_args, char *errstring,
 	      return_mask mask)

gdb/exceptions.h

@@ -180,7 +180,7 @@ extern NORETURN void deprecated_throw_reason (enum return_reason reason) ATTR_NO
    throw_exception() than all cleanups installed since
    catch_exceptions() was entered are invoked, the (-ve) exception
    value is then returned by catch_exceptions.  If FUNC() returns
-   normally (with a postive or zero return value) then that value is
+   normally (with a positive or zero return value) then that value is
    returned by catch_exceptions().  It is an internal_error() for
    FUNC() to return a negative value.
 
@@ -194,10 +194,19 @@ extern NORETURN void deprecated_throw_reason (enum return_reason reason) ATTR_NO
    copy of the gdb error message.  This is used when a silent error is 
    issued and the caller wants to manually issue the error message.
 
+   MASK specifies what to catch; it is normally set to
+   RETURN_MASK_ALL, if for no other reason than that the code which
+   calls catch_errors might not be set up to deal with a quit which
+   isn't caught.  But if the code can deal with it, it generally
+   should be RETURN_MASK_ERROR, unless for some reason it is more
+   useful to abort only the portion of the operation inside the
+   catch_errors.  Note that quit should return to the command line
+   fairly quickly, even if some further processing is being done.
+
    FIXME; cagney/2001-08-13: The need to override the global UIOUT
    builder variable should just go away.
 
-   This function superseeds catch_errors().
+   This function supersedes catch_errors().
 
    This function uses SETJMP() and LONGJUMP().  */
 
@@ -228,7 +237,7 @@ extern struct gdb_exception catch_exception (struct ui_out *uiout,
    indication of the exact exception that it caught - quit_flag might
    help.
 
-   This function is superseeded by catch_exceptions().  */
+   This function is superseded by catch_exceptions().  */
 
 typedef int (catch_errors_ftype) (void *);
 extern int catch_errors (catch_errors_ftype *, void *, char *, return_mask);