Re: [whatwg/webidl] Allow DOMException subclasses to be used as exceptions (PR #1211)

@annevk commented on this pull request.

Let me introduce you to https://w3c.github.io/webrtc-pc/#dom-rtcerror which follows almost none of these guidelines and promises are rejected with instances of it already as far as I can tell.

>      </blockquote>
 </div>
 
+<div class=example id=example-exception-throwing-message-hint>
+    <p>An example of including additional information used to construct the [=exception/message=]
+    would be:
+
+    <blockquote>
+        [=exception/Throw=] a "{{SyntaxError}}" {{DOMException}} indicating that the given value
+        had disallowed trailing spaces.
+    </blockquote>
+
+    <p>Such additional context is most helpful to implementers when it is not immediately obvious
+    why the exception is being thrown, e.g., because there are many different steps in the algorithm
+    which throw "{{SyntaxError}}" {{DOMException}}s. In contrast, if your specification throws a

```suggestion
    which throw a "{{SyntaxError}}" {{DOMException}}. In contrast, if your specification throws a
```

> +<div class=example id=example-exception-throwing-message-hint>
+    <p>An example of including additional information used to construct the [=exception/message=]
+    would be:
+
+    <blockquote>
+        [=exception/Throw=] a "{{SyntaxError}}" {{DOMException}} indicating that the given value
+        had disallowed trailing spaces.
+    </blockquote>
+
+    <p>Such additional context is most helpful to implementers when it is not immediately obvious
+    why the exception is being thrown, e.g., because there are many different steps in the algorithm
+    which throw "{{SyntaxError}}" {{DOMException}}s. In contrast, if your specification throws a
+    "{{NotAllowedError}}" {{DOMException}} immediately after checking if the user has provided
+    permission to use a given feature, it's fairly obvious what sort of [=exception/message=] the
+    implementation should construct, and so specifying it is not necessary.
+</div>

We should add here that "context" cannot be given in all situations and that user agents have to be careful not to introduce additional tracking vectors.

> -a {{DOMString}},
-which is the type of error the exception represents, and a
-<dfn id="dfn-exception-message" for="exception" export>message</dfn>, which is an optional,
-user agent-defined value that provides human readable details of the error.
-
-There are two kinds of exceptions available to be thrown from specifications.
-The first is a <dfn id="dfn-simple-exception" export>simple exception</dfn>, which
-is identified by one of the following types:
+An <dfn id="dfn-exception" export>exception</dfn> is a type of object that represents an error and
+which can be thrown or treated as a first class value by implementations. Web IDL has a number of
+pre-defined exceptions that specifications can reference and throw in their definition of
+operations, attributes, and so on. Custom exception types can also be defined, as [=interfaces=]
+that [=interface/inherit=] from {{DOMException}}.
+
+In addition to their type, which is either one of the [=simple exceptions=], {{DOMException}}, or a
+derived interface of {{DOMException}}, all exceptions have a

Off-topic: it might be nice to `<dfn>` derived at some point as it's quite a distinct term from inherit and it might confuse some readers.

>  
     <blockquote>
-        Let <var ignore>object</var> be a newly [=created=] "{{SyntaxError!!exception}}" {{DOMException}}.
+        <p>Let <var ignore>object</var> be a newly [=created=] "{{SyntaxError}}" {{DOMException}}.
     </blockquote>

Optional: perhaps add a promise example while here.

>  </div>
 
-<div algorithm="throw an exception">
+<div algorithm="to create a DOMException">
+    To create a {{DOMException}} given [=error name=] |name|:
+
+    1.  Let |ex| be a [=new=] {{DOMException}} created in the [=current Realm=].

realm*
```suggestion
    1.  Let |ex| be a [=new=] {{DOMException}} created in the [=current realm=].
```

> -             :  |E| is a [=simple exception=]
-             :: |args| is «|M|».
-        </dl>
-    1.  Let |X| be an object determined based on the type of |E|:
-        <dl class="switch">
-             :  |E| is {{DOMException}}
-             :: |X| is the {{DOMException}} [=interface object=]
-                from the [=current Realm=].
-             :  |E| is a [=simple exception=]
-             :: |X| is the [=constructor=] for the corresponding ECMAScript error
-                from the [=current Realm=].
-        </dl>
-    1.  Return [=!=] <a abstract-op>Construct</a>(|X|, |args|).
+    1.  Let |args| be « |message| ».
+
+    1.  Let |constructor| be [=current Realm=].\[[Intrinsics]].[[%|T|%]].

```suggestion
    1.  Let |constructor| be [=current realm=].\[[Intrinsics]].[[%|T|%]].
```

>  
-    To [=exception/throw=] a [=simple exception=] or {{DOMException}}, with a string giving the
-    [=error name=] for the {{DOMException}} case and optionally a string giving a user
-    agent-defined message:
+    1.  Let |ex| be a [=new=] instance of the [=interface=] identified by |type|, created in the
+        [=current Realm=].

```suggestion
        [=current realm=].
```

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/webidl/pull/1211#pullrequestreview-1135797124

You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/webidl/pull/1211/review/1135797124@github.com>