Re: Soft errors and ThrowErrorData() comment updates

On Wed, Oct 16, 2024 at 4:20 PM Jeff Davis <pgsql(at)j-davis(dot)com> wrote:

> The comments around ThrowErrorData() and how it might apply to soft
> errors is slightly confusing. Attached a patch which hopefully
> clarifies things.
>
> From a distance, ThrowErrorData() is somewhat like ReThrowError(), but
> it's actually quite different. The former is expecting a free-standing
> ErrorData that hasn't been processed at all; while the latter is for an
> ERROR specifically, for which errstart() and errfinish() have already
> been called.
>
> We also might consider adding some asserts.
>
> Regards,
> Jeff Davis
>
>
I think this is a good move. The existing docs are focused on the one usage
the function currently has, and it seems to be more general purpose than
that.

Total nitpick:

+ * callee's memory context!). The ErrorData can be modified (i.e.
downgraded
+ * to a WARNING) and reported with ThrowErrorData(). FreeErrorData() can
be

Suggest:

Change "i.e." to "example:". Downgrading elevel is just one possible
(though the most likely) use of the function, but there are others, and
"i.e" means "that is", which implies that what follows is the one and only
use.