From 4984548cab3f85c742588e4c07446c4fce4de0b0 Mon Sep 17 00:00:00 2001
From: Steve Gravrock <sdg@panix.com>
Date: Fri, 22 Mar 2024 08:53:19 -0700
Subject: [PATCH] Clarify argument to spyOnGlobalErrorsAsync's spy

---
 lib/jasmine-core/jasmine.js | 8 ++++++++
 src/core/GlobalErrors.js    | 2 ++
 src/core/base.js            | 6 ++++++
 3 files changed, 16 insertions(+)

diff --git a/lib/jasmine-core/jasmine.js b/lib/jasmine-core/jasmine.js
index 075c3689..da335b71 100644
--- a/lib/jasmine-core/jasmine.js
+++ b/lib/jasmine-core/jasmine.js
@@ -611,6 +611,12 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
    * handling will be restored when the promise returned from the callback is
    * settled.
    *
+   * When the JavaScript runtime reports an uncaught error or unhandled rejection,
+   * the spy will be called with a single parameter representing Jasmine's best
+   * effort at describing the error. This parameter may be of any type, because
+   * JavaScript allows anything to be thrown or used as the reason for a
+   * rejected promise, but Error instances and strings are most common.
+   *
    * Note: The JavaScript runtime may deliver uncaught error events and unhandled
    * rejection events asynchronously, especially in browsers. If the event
    * occurs after the promise returned from the callback is settled, it won't
@@ -4076,6 +4082,7 @@ getJasmineRequireObj().GlobalErrors = function(j$) {
 
     function dispatchBrowserError(error, event) {
       if (overrideHandler) {
+        // See discussion of spyOnGlobalErrorsAsync in base.js
         overrideHandler(error);
         return;
       }
@@ -4119,6 +4126,7 @@ getJasmineRequireObj().GlobalErrors = function(j$) {
         const handler = handlers[handlers.length - 1];
 
         if (overrideHandler) {
+          // See discussion of spyOnGlobalErrorsAsync in base.js
           overrideHandler(error);
           return;
         }
diff --git a/src/core/GlobalErrors.js b/src/core/GlobalErrors.js
index f5d6524e..d9d298ac 100644
--- a/src/core/GlobalErrors.js
+++ b/src/core/GlobalErrors.js
@@ -12,6 +12,7 @@ getJasmineRequireObj().GlobalErrors = function(j$) {
 
     function dispatchBrowserError(error, event) {
       if (overrideHandler) {
+        // See discussion of spyOnGlobalErrorsAsync in base.js
         overrideHandler(error);
         return;
       }
@@ -55,6 +56,7 @@ getJasmineRequireObj().GlobalErrors = function(j$) {
         const handler = handlers[handlers.length - 1];
 
         if (overrideHandler) {
+          // See discussion of spyOnGlobalErrorsAsync in base.js
           overrideHandler(error);
           return;
         }
diff --git a/src/core/base.js b/src/core/base.js
index 4e1bf8df..ce620739 100644
--- a/src/core/base.js
+++ b/src/core/base.js
@@ -435,6 +435,12 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
    * handling will be restored when the promise returned from the callback is
    * settled.
    *
+   * When the JavaScript runtime reports an uncaught error or unhandled rejection,
+   * the spy will be called with a single parameter representing Jasmine's best
+   * effort at describing the error. This parameter may be of any type, because
+   * JavaScript allows anything to be thrown or used as the reason for a
+   * rejected promise, but Error instances and strings are most common.
+   *
    * Note: The JavaScript runtime may deliver uncaught error events and unhandled
    * rejection events asynchronously, especially in browsers. If the event
    * occurs after the promise returned from the callback is settled, it won't