[web-animations-1] Make async methods on Animation return appropriate Promise objects (#2799)

This closes #2206.

Author: birtles

web-animations-1/Overview.bs

@@ -1245,8 +1245,7 @@ as CSS Animations [[CSS-ANIMATIONS-1]].
     implementations:
 
     <div class='example'><pre class='lang-javascript'>
-    animation.play();
-    animation.ready.then(
+    animation.play().then(
       () => { console.log('Playback commenced'); },
       () => { console.log('Playback was canceled'); }
     );
@@ -3953,10 +3952,10 @@ interface Animation : EventTarget {
              attribute EventHandler             oncancel;
     void cancel ();
     void finish ();
-    void play ();
-    void pause ();
-    void updatePlaybackRate (double playbackRate);
-    void reverse ();
+    Promise&lt;Animation&gt; play ();
+    Promise&lt;Animation&gt; pause ();
+    Promise&lt;Animation&gt; updatePlaybackRate (double playbackRate);
+    Promise&lt;Animation&gt; reverse ();
 };
 </pre>
 
@@ -4071,35 +4070,46 @@ interface Animation : EventTarget {
 
     </div>
 
-:   <dfn method for=Animation lt='play()'>void play()</dfn>
-::  Unpauses the animation and rewinds if it has finished playing using
-    the procedure to <a>play an animation</a> for this object
-    with the <var>auto-rewind</var> flag set to true.
-:   <dfn method for=Animation lt='pause()'>void pause()</dfn>
+:   <dfn method for=Animation lt='play()'>Promise&lt;Animation&gt; play()</dfn>
+::  Begins or resumes playback of the animation by running the procedure to
+    [=play an animation=] passing true as the value of the |auto-rewind| flag.
+
+    Returns the animation's [=current finished promise=] at the moment
+    immediately after performing the [=play an animation=] procedure.
+:   <dfn method for=Animation lt='pause()'>Promise&lt;Animation&gt; pause()</dfn>
 ::  Suspends the playback of this animation by running the procedure to
     <a>pause an animation</a> for this object.
-:   <dfn method for=Animation lt='updatePlaybackRate(playbackRate)'>void updatePlaybackRate(playbackRate)</dfn>
+
+    Returns the animation's [=current ready promise=] at the moment
+    immediately after performing the [=pause an animation=] procedure.
+:   <dfn method for=Animation lt='updatePlaybackRate(playbackRate)'>Promise&lt;Animation&gt; updatePlaybackRate(playbackRate)</dfn>
 ::  Performs an asynchronous update of the [=playback rate=] of this
     animation by performing the [=seamlessly update the playback rate=]
     procedure, passing
     {{Animation/updatePlaybackRate(playbackRate)/playbackRate}} as the |new
     playback rate|.
 
+    Returns the animation's [=current ready promise=] at the moment immediately
+    after performing the [=seamlessly update the playback rate=] procedure.
+
     <div class="parameters">
 
     :   <dfn argument for="Animation/updatePlaybackRate(playbackRate)"
         lt="playbackRate">playbackRate</dfn>
     ::  A finite real number specifying the updated playback rate to use.
 
     </div>
-:   <dfn method for=Animation lt='reverse()'>void reverse()</dfn>
+:   <dfn method for=Animation lt='reverse()'>Promise&lt;Animation&gt; reverse()</dfn>
 ::  Inverts the [=playback rate=] of this animation and plays it using the
     <a>reverse an animation</a> procedure for this object.
     As with <a method for=Animation lt="play()">play()</a>, this
     method unpauses the animation and, if the animation has already finished
     playing in the reversed direction, seeks to the start of the <a>target
     effect</a>.
 
+    Returns the animation's [=current finished promise=] at the moment
+    immediately after performing the [=reverse an animation=] procedure.
+
 </div>
 
 <h4 id="the-animationplaystate-enumeration">The <code>AnimationPlayState</code> enumeration</h4>
@@ -5959,6 +5969,10 @@ The following changes have been made since the <a
         {{AnimationEffect/updateTiming}} method.
     *   Removed <code>KeyframeEffectReadOnly</code>, leaving only
         {{KeyframeEffect}}.
+*   Made the {{Animation/play()}} and {{Animation/reverse()}} methods on
+    {{Animation}} return the animation's [=current finished promise=],
+    and the {{Animation/pause()}} and {{Animation/updatePlaybackRate()}} methods
+    return the animation's [=current ready promise=].
 *   Added special handling to allow animating the 'offset' property from the
     programming interface using <code>cssOffset</code> to avoid conflict with
     the attribute name used to specify keyframe offsets.