jQuery.Deferred.getErrorHook: Create the page

Also, create a page for the now deprecated `jQuery.Deferred.getStackHook` and
update the `jQuery.readyException` docs to mention the async error.

Fixes gh-1221

Author: mgol

categories.xml

@@ -108,6 +108,12 @@
         <p>For more information, see the Release Notes/Changelog at <a href="https://blog.jquery.com/2020/04/10/jquery-3-5-0-released/">https://blog.jquery.com/2020/04/10/jquery-3-5-0-released/</a></p>
       ]]></desc>
     </category>
+    <category name="Deprecated 3.7" slug="deprecated-3.7">
+      <desc><![CDATA[
+        <p>All the aspects of the API that were deprecated in the corresponding version of jQuery.</p>
+        <p>For more information, see the Release Notes/Changelog at <a href="https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/">https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/</a></p>
+      ]]></desc>
+    </category>
   </category>
   <category name="Dimensions" slug="dimensions">
     <desc><![CDATA[These methods are used to get and set the CSS dimensions for the various properties.]]></desc>

entries/jQuery.Deferred.getErrorHook.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<entry type="method" name="jQuery.Deferred.getErrorHook" return="Error">
+  <title>jQuery.Deferred.getErrorHook()</title>
+  <signature>
+    <added>3.7</added>
+  </signature>
+  <desc>Return an Error instance with a defined stack.</desc>
+  <longdesc>
+    <div class="warning">
+      <p>Note: This API is not defined by default. It may be provided by the user and jQuery will then use it internally.</p>
+    </div>
+    <p>When <code>jQuery.Deferred.getErrorHook</code> is defined, it extends the <code>jQuery.Deferred</code> features added in jQuery 3.0 to include an error captured before the async barrier whenever a Deferred throws an exception. This makes it easier to find programming errors that occur inside Deferreds. You can find an example implementation you can copy-paster below, or you can use <a href="https://github.com/dmethvin/jquery-deferred-reporter">jquery-deferred-reporter</a> plugin.</p>
+    <pre><code>
+jQuery.Deferred.getErrorHook = function() {
+  try {
+    throw new Error( "Exception in jQuery.Deferred" );
+  } catch ( err ) {
+    return err;
+  }
+};
+    </code></pre>
+    <h4>Why does this API exist?</h4>
+    <p>Prior to jQuery 3.0, Deferreds would simply terminate and the browser would generate a message on the console if an exception occurred such as attempting to call an undefined method as a function (e.g., <code>myobject.missingFunction()</code>). As of version 3.0, <code>jQuery.Deferred</code> follows the Promise/A+ specification when you use the <code>.then</code> method. The spec requires all errors to be trapped by the Promise, which prevents console errors from being logged. If the user has forgotten to add a handler for rejected promises, this can result in the error being silently swallowed with no notification at all!</p>
+    <p>The native <code>Promise</code> object as implemented in the browser tracks Promise rejections and reports problems on the console. However, doing the same type of reporting in the JavaScript world is much more difficult. jQuery itself is unable to use the native Promise because jQuery.Deferred implements a superset of Promise that requires additional features for methods like <code>.done</code> or <code>.fail</code>, and because Promise is not implemented on all the platforms that jQuery supports.</p>
+  </longdesc>
+  <category slug="deferred-object"/>
+  <category slug="version/3.7"/>
+</entry>

entries/jQuery.Deferred.getStackHook.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<entry type="method" name="jQuery.Deferred.getStackHook" return="Error" deprecated="3.7" removed="4.0">
+  <title>jQuery.Deferred.getStackHook()</title>
+  <signature>
+    <added>3.0</added>
+  </signature>
+  <desc>Return an Error instance with a defined stack.</desc>
+  <longdesc>
+    <div class="warning">
+      <p>Note: This API has been deprecated in jQuery 3.7; please use the <a href="/jQuery.Deferred.getErrorHook/"><code>jQuery.Deferred.getErrorHook</code></a> method instead.</p>
+    </div>
+    <div class="warning">
+      <p>Note: This API is not defined by default. It may be provided by the user and jQuery will then use it internally.</p>
+    </div>
+    <p>See <a href="/jQuery.Deferred.getErrorHook/"><code>jQuery.Deferred.getErrorHook</code></a> for the context why this API was created. Initially, we advised users to assign to it a function returning an error stack:</p>
+    <pre><code>
+jQuery.Deferred.getStackHook = function() {
+  try {
+    throw new Error( "Exception in jQuery.Deferred" );
+  } catch ( err ) {
+    return err.stack; // stack property returned here
+  }
+};
+    </code></pre>
+    <p>However, when such a stack is then logged by jQuery from inside of <a href="/jQuery.Deferred.exceptionHook/"><code>jQuery.Deferred.exceptionHook</code></a>, the browser won't apply source maps. Therefore, we changed the recommendation to return the full error object itself. To make it clearer, the API was also renamed.</p>
+  </longdesc>
+  <category slug="deferred-object"/>
+  <category slug="version/3.0"/>
+  <category slug="deprecated/deprecated-3.7"/>
+</entry>

entries/jQuery.readyException.xml

@@ -9,13 +9,13 @@
     </argument>
   </signature>
   <longdesc>
-    <p>This method is fired when an error is thrown synchronously in a function wrapped in <code>jQuery()</code> or <code>jQuery( document ).ready()</code>, or equivalent. By default it re-throws the error in a timeout so that it's logged in the console and passed to <code>window.onerror</code> instead of being swallowed. Overwrite this method if you want to handle such errors differently.</p>
+    <p>This method is fired when an error is thrown synchronously in a function wrapped in <code>jQuery()</code> or <code>jQuery( document ).ready()</code>, or equivalent. By default, it re-throws the error in a timeout so that it's logged in the console and passed to <code>window.onerror</code> instead of being swallowed. Overwrite this method if you want to handle such errors differently.</p>
   </longdesc>
   <example>
-    <desc>Pass the received error to <code>console.error</code>.</desc>
+    <desc>Pass the received errors to <code>console.error</code>. The second parameter is defined if <a href="/jQuery.Deferred.getErrorHook/"><code>jQuery.Deferred.getErrorHook</code></a> is defined.</desc>
     <code><![CDATA[
-jQuery.readyException = function( error ) {
-  console.error( error );
+jQuery.readyException = function( error, asyncError ) {
+  console.error( error, asyncError );
 };
 ]]></code>
   </example>