From 982c7e2b710326167d718b85f83a5734fdb5619d Mon Sep 17 00:00:00 2001
From: Anne van Kesteren <annevk@annevk.nl>
Date: Mon, 6 Dec 2021 10:51:58 +0100
Subject: [PATCH] Aborting: clarify usage for non-promise APIs

Also clean up some remaining instances that didn't use signal.reason.

Closes #961.
---
 dom.bs | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/dom.bs b/dom.bs
index 5d7c0ce2..5e04fed6 100644
--- a/dom.bs
+++ b/dom.bs
@@ -1667,7 +1667,7 @@ The API which wishes to support aborting can accept an {{AbortSignal}} object, a
 determine how to proceed.
 
 <p>APIs that rely upon {{AbortController}} are encouraged to respond to {{AbortController/abort()}}
-by rejecting any unsettled promise with a new "{{AbortError!!exception}}" {{DOMException}}.
+by rejecting any unsettled promise with the {{AbortSignal}}'s [=AbortSignal/abort reason=].
 
 <div class=example id=aborting-ongoing-activities-example>
  <p>A hypothetical <code>doAmazingness({ ... })</code> method could accept an {{AbortSignal}} object
@@ -1696,7 +1696,7 @@ controller.abort();</code></pre>
  <pre><code class=lang-javascript>
 function doAmazingness({signal}) {
   if (signal.aborted) {
-    return Promise.reject(new DOMException('Aborted', 'AbortError'));
+    return Promise.reject(signal.reason);
   }
 
   return new Promise((resolve, reject) => {
@@ -1704,16 +1704,20 @@ function doAmazingness({signal}) {
     // But also, watch for signals:
     signal.addEventListener('abort', () => {
       // Stop doing amazingness, and:
-      reject(new DOMException('Aborted', 'AbortError'));
+      reject(signal.reason);
     });
   });
 }
 </code></pre>
-
- <p>APIs that require more granular control could extend both {{AbortController}} and
- {{AbortSignal}} objects according to their needs.
 </div>
 
+<p>APIs that do not return promises can either react in an equivalent manner or opt to not surface
+the {{AbortSignal}}'s [=AbortSignal/abort reason=] at all. {{EventTarget/addEventListener()}} is an
+example of an API where the latter made sense.
+
+<p>APIs that require more granular control could extend both {{AbortController}} and
+{{AbortSignal}} objects according to their needs.
+
 
 <h3 id=interface-abortcontroller>Interface {{AbortController}}</h3>