Improve ThrowErrorData() comments for use with soft errors.

Reviewed-by: Corey Huinker
Discussion: https://postgr.es/m/901ab7cf01957f92ea8b30b6feeb0eacfb7505fc.camel@j-davis.com

Author: jeff-davis

src/backend/utils/error/elog.c

@@ -1881,12 +1881,15 @@ FlushErrorState(void)
 /*
  * ThrowErrorData --- report an error described by an ErrorData structure
  *
- * This is somewhat like ReThrowError, but it allows elevels besides ERROR,
- * and the boolean flags such as output_to_server are computed via the
- * default rules rather than being copied from the given ErrorData.
- * This is primarily used to re-report errors originally reported by
- * background worker processes and then propagated (with or without
- * modification) to the backend responsible for them.
+ * This function should be called on an ErrorData structure that isn't stored
+ * on the errordata stack and hasn't been processed yet. It will call
+ * errstart() and errfinish() as needed, so those should not have already been
+ * called.
+ *
+ * ThrowErrorData() is useful for handling soft errors. It's also useful for
+ * re-reporting errors originally reported by background worker processes and
+ * then propagated (with or without modification) to the backend responsible
+ * for them.
  */
 void
 ThrowErrorData(ErrorData *edata)

src/include/nodes/miscnodes.h

@@ -36,9 +36,10 @@
  * After calling code that might report an error this way, check
  * error_occurred to see if an error happened.  If so, and if details_wanted
  * is true, error_data has been filled with error details (stored in the
- * callee's memory context!).  FreeErrorData() can be called to release
- * error_data, although that step is typically not necessary if the called
- * code was run in a short-lived context.
+ * callee's memory context!).  The ErrorData can be modified (e.g. downgraded
+ * to a WARNING) and reported with ThrowErrorData().  FreeErrorData() can be
+ * called to release error_data, although that step is typically not necessary
+ * if the called code was run in a short-lived context.
  */
 typedef struct ErrorSaveContext
 {