- From: Anne van Kesteren <notifications@github.com>
- Date: Mon, 10 Oct 2022 03:34:40 -0700
- To: whatwg/webidl <webidl@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <whatwg/webidl/pull/1211/review/1135797124@github.com>
@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>
Received on Monday, 10 October 2022 10:34:53 UTC