Play/pause now properly return Promises (katspaugh#1229)

* Play/pause now properly return Promises
* add changelog entry
* document promise returns

CHANGES.md

@@ -5,13 +5,14 @@ next (unreleased)
 -----------------
 
 - Added support for selecting different audio output devices using `setSinkId` (#1293)
+- Play method now properly returns a Promise (#1229)
 
 2.0.2 (10.01.2018)
 ------------------
 
 - Added `barGap` parameter to set the space between bars (#1058)
 - Replace deprecated gain.value setter (#1277)
-- MediaElement backend: Update progress on pause events (#1267) 
+- MediaElement backend: Update progress on pause events (#1267)
 - Restore missing MediaSession plugin (#1286)
 
 2.0.1 (18.12.2017)

src/mediaelement.js

@@ -246,23 +246,33 @@ export default class MediaElement extends WebAudio {
      *
      * @param {number} start Start offset in seconds, relative to the beginning
      * of a clip.
-     * @param {number} end When to stop relative to the beginning of a clip.
+     * @param {number} end When to stop, relative to the beginning of a clip.
      * @emits MediaElement#play
+     * @return {Promise}
      */
     play(start, end) {
         this.seekTo(start);
-        this.media.play();
+        const promise = this.media.play();
         end && this.setPlayEnd(end);
+
+        return promise;
     }
 
     /**
      * Pauses the loaded audio.
      *
      * @emits MediaElement#pause
+     * @return {Promise}
      */
     pause() {
-        this.media && this.media.pause();
+        let promise;
+
+        if (this.media) {
+            promise = this.media.pause();
+        }
         this.clearPlayEnd();
+
+        return promise;
     }
 
     /** @private */

src/wavesurfer.js

@@ -647,31 +647,36 @@ export default class WaveSurfer extends util.Observer {
      * @param {?number} start Position to start at
      * @param {?number} end Position to end at
      * @emits WaveSurfer#interaction
+     * @return {Promise}
      * @example
      * // play from second 1 to 5
      * wavesurfer.play(1, 5);
      */
     play(start, end) {
         this.fireEvent('interaction', () => this.play(start, end));
-        this.backend.play(start, end);
+        return this.backend.play(start, end);
     }
 
     /**
      * Stops playback
      *
      * @example wavesurfer.pause();
+     * @return {Promise}
      */
     pause() {
-        this.backend.isPaused() || this.backend.pause();
+        if (!this.backend.isPaused()) {
+            return this.backend.pause();
+        }
     }
 
     /**
      * Toggle playback
      *
      * @example wavesurfer.playPause();
+     * @return {Promise}
      */
     playPause() {
-        this.backend.isPaused() ? this.play() : this.pause();
+        return this.backend.isPaused() ? this.play() : this.pause();
     }
 
     /**