[web-animations-1] Add annotations describing exceptions thrown by the API

Fixes #2050.

Author: birtles

web-animations-1/Overview.bs

@@ -4589,6 +4589,15 @@ Programming interface {#programming-interface}
 
 </div>
 
+Exception annotations in this section list exceptions
+that originate from algorithms in this specification.
+They do not repeat exceptions produced by
+converting values according to Web IDL.
+The procedures for processing keyframes also propagate exceptions
+thrown by author-defined property accessors or iterator methods.
+Since such exceptions can be of any type,
+they are not enumerated in these annotations.
+
 Time values in the programming interface {#time-values-in-the-programming-interface}
 ----------------------------------------
 
@@ -4901,8 +4910,8 @@ The {{Animation}} interface {#the-animation-interface}
 
       : {{DOMException}} of type "{{InvalidStateError}}"
       ::
-          Raised if this animation's [=playback rate=] is zero,
-          or if this animation's [=playback rate=] is > zero
+          Raised if this animation's [=effective playback rate=] is zero,
+          or if this animation's [=effective playback rate=] is > zero
           and the [=associated effect end=] is infinity.
 
       </div>
@@ -4913,12 +4922,33 @@ The {{Animation}} interface {#the-animation-interface}
       by running the procedure to [=play an animation=]
       passing true as the value of the |auto-rewind| flag.
 
+      <div class=exceptions>
+
+      : {{DOMException}} of type "{{InvalidStateError}}"
+      ::
+          Raised if this animation's [=effective playback rate=] is negative,
+          the [=associated effect end=] is infinity,
+          and its [=animation/current time=] is unresolved
+          or less than or equal to zero.
+
+      </div>
+
   : <dfn lt="pause()">void pause()</dfn>
   ::
       Suspends the playback of this animation
       by running the procedure to [=pause an animation=]
       for this object.
 
+      <div class=exceptions>
+
+      : {{DOMException}} of type "{{InvalidStateError}}"
+      ::
+          Raised if this animation's [=animation/current time=] is unresolved,
+          its [=playback rate=] is negative,
+          and the [=associated effect end=] is infinity.
+
+      </div>
+
     <wpt>
       interfaces/Animation/pause.html
     </wpt>
@@ -4950,6 +4980,18 @@ The {{Animation}} interface {#the-animation-interface}
       if the animation has already finished playing in the reversed direction,
       [=seeks=] to the start of the [=associated effect=].
 
+      <div class=exceptions>
+
+      : {{DOMException}} of type "{{InvalidStateError}}"
+      ::
+          Raised if this animation has no associated [=active timeline=],
+          or if its reversed [=effective playback rate=] would be negative,
+          the [=associated effect end=] is infinity,
+          and its [=animation/current time=] is unresolved
+          or less than or equal to zero.
+
+      </div>
+
   : <dfn lt="persist()">void persist()</dfn>
   ::
       Sets this animation's [=replace state=]
@@ -4966,6 +5008,19 @@ The {{Animation}} interface {#the-animation-interface}
       calling this method <em>does</em> trigger a [=style change event=]
       (see [[#model-liveness]]).
 
+      <div class=exceptions>
+
+      : {{DOMException}} of type "{{NoModificationAllowedError}}"
+      ::
+          Raised if any [=effect target=] is not an element
+          capable of having a [=style attribute=].
+
+      : {{DOMException}} of type "{{InvalidStateError}}"
+      ::
+          Raised if any [=effect target=] is not [=being rendered=].
+
+      </div>
+
       <wpt>
         interfaces/Animation/commitStyles.html
       </wpt>
@@ -5240,6 +5295,22 @@ The {{AnimationEffect}} interface {#the-animationeffect-interface}
 
       </div>
 
+      <div class=exceptions>
+
+      : {{TypeError}}
+      ::
+          Raised if any of the following conditions applies:
+
+          * {{EffectTiming/iterationStart}} is negative;
+          * {{EffectTiming/iterations}} is negative
+              or <code class=esvalue>NaN</code>;
+          * {{EffectTiming/duration}} is negative,
+              <code class=esvalue>NaN</code>,
+              or a string other than `auto`; or
+          * {{EffectTiming/easing}} cannot be parsed as an <<easing-function>>.
+
+      </div>
+
   </div>
 
   Issue(2082): The <code>remove()</code> method can be used to remove an effect
@@ -5960,6 +6031,18 @@ The {{KeyframeEffect}} interface {#the-keyframeeffect-interface}
 
       </div>
 
+      <div class=exceptions>
+
+      : {{TypeError}}
+      ::
+          Raised if an iterable yields a value other than `undefined`, `null`,
+          or an object;
+          if the keyframes are not [=loosely sorted by offset=];
+          if a non-null [=keyframe offset=] is outside the range [0, 1];
+          or if an easing cannot be parsed as an <<easing-function>>.
+
+      </div>
+
   </div>
 
 ### Creating a new <code>KeyframeEffect</code> object ### {#creating-a-new-keyframeeffect-object}
@@ -6866,6 +6949,21 @@ The <code>Animatable</code> interface mixin {#the-animatable-interface-mixin}
 
       </div>
 
+      <div class=exceptions>
+
+      : {{TypeError}}
+      ::
+          Raised under the conditions described for
+          {{AnimationEffect/updateTiming()}} or
+          {{KeyframeEffect/setKeyframes()}}.
+
+      : {{DOMException}} of type "{{SyntaxError}}"
+      ::
+          Raised if the {{KeyframeEffectOptions/pseudoElement}} option
+          is not `null` and is an invalid <<pseudo-element-selector>>.
+
+      </div>
+
   : <dfn lt="getAnimations(options)">sequence&lt;Animation&gt; getAnimations(|options|)</dfn>
   ::
       1. Let |object| be the object on which this method was called.
@@ -6906,6 +7004,15 @@ The <code>Animatable</code> interface mixin {#the-animatable-interface-mixin}
 
       </div>
 
+      <div class=exceptions>
+
+      : {{DOMException}} of type "{{SyntaxError}}"
+      ::
+          Raised if the {{GetAnimationsOptions/pseudoElement}} option
+          is not `null` and is an invalid <<pseudo-element-selector>>.
+
+      </div>
+
   </div>
 
   <div dfn-type=dict-member class=members>
@@ -7339,7 +7446,9 @@ Changes since last publication {#changes-since-last-publication}
   The following changes have been made since the
   <a href="https://www.w3.org/TR/2023/WD-web-animations-1-20230605/">5 June 2023 Working Draft</a>:
 
-  (Nothing yet)
+  * Added annotations describing exceptions thrown by methods
+      in the [[#programming-interface]].
+      (<a href="https://github.com/w3c/csswg-drafts/issues/2050">Issue 2050</a>)
 
   The <a href="https://github.com/w3c/csswg-drafts/commits/main/web-animations-1">changelog</a>
   provides a more detailed history.