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

@annevk commented on this pull request.

I found a couple nits, looks great overall.

> -    [=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=].
+
+    1.  Set |ex|'s [=DOMException/name=] to |type|.
+
+    1.  Set |ex|'s [=DOMException/message=] to an [=implementation-defined=] message appropriate for
+        the exceptional situation. The calling specification may contain information to to help
+        implementations construct this message.
+
+        Implementations need to be cautious not to leak sensitive or secured information when
+        constructing this message, e.g., by including the URL of a cross-origin frame, or
+        information which could identify the user.
+
+    1.  Initialize |ex|'s additionally as described by the caller.

I don't think this is English?

> -<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
+<dfn id="dfn-exception-message" for="exception" export>message</dfn>, which is an
+[=implementation-defined=] [=string=] that provides human readable details of the error.

```suggestion
[=implementation-defined=] [=string=] that provides human-readable details of the error.
```

>  
-<p class="warning">
-    The {{DOMException}} names marked as deprecated are kept for legacy purposes but their usage is discouraged.
-</p>
+The resulting behavior from creating and throwing an exception is language binding-specific.

```suggestion
The resulting behavior from creating and throwing an exception is language-binding specific.
```
(Or maybe hyphens everywhere?)

>  
-Note: If an error name is not listed here, please file a bug as indicated at the top of this specification and it will be addressed shortly. Thanks!
+When [=exception/creating=] or [=exception/throwing=] a {{DOMException}}, specifications must use
+one of these names. If a specification author believes none of these names are a good fit for their
+case, they must
+<a href="https://github.com/heycam/webidl/issues/new?title=DOMException%20name%20proposal">file an issue</a>

```suggestion
<a href="https://github.com/whatwg/webidl/issues/new?title=DOMException%20name%20proposal">file an issue</a>
```

> -
-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
+<dfn id="dfn-exception-message" for="exception" export>message</dfn>, which is an
+[=implementation-defined=] [=string=] that provides human readable details of the error.
+{{DOMException}} instances also have an
+<dfn id="dfn-exception-error-name" for="exception" export>error name</dfn> [=string=], which

It's weird that we have error name here, but then for `DOMException` we also define an internal name field. I don't think we need both? Message seems similarly duplicated.

> +    [=deserialization steps=] preserve the additional information.
+
+<p class=note>These requirements mean that the inherited {{DOMException/code}} property of these
+interfaces will always return 0.
+
+<div class=example id=example-domexception-derived-interface>
+    The definition for a {{DOMException}} derived interface which carries along an additional
+    "hardware error code", for interfacing with a hypothetical Widget hardware device, could look
+    something like this:
+
+    <pre highlight=webidl>
+        [Exposed=Window]
+        interface WidgetError : DOMException {
+          constructor(optional DOMString message = "", WidgetErrorOptions options);
+
+          readonly attribute unsigned long long hardwareErrorCode;

Perhaps we ought to encourage an enum instead?

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/webidl/pull/1211#pullrequestreview-1158414495
You are receiving this because you are subscribed to this thread.

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