From 97e2996090f3c5acecb641d81f5decb6974cc03d Mon Sep 17 00:00:00 2001
From: "Michael \"Z\" Goddard" <mzgoddard@gmail.com>
Date: Fri, 22 Jun 2018 14:43:37 -0400
Subject: [PATCH] add missing docs: SoundPlayer, AudioEngine, Effect.name

---
 src/AudioEngine.js          |  9 +++++
 src/SoundPlayer.js          | 67 +++++++++++++++++++++++++++++++++----
 src/effects/PanEffect.js    |  4 +++
 src/effects/PitchEffect.js  |  4 +++
 src/effects/VolumeEffect.js |  4 +++
 5 files changed, 81 insertions(+), 7 deletions(-)

diff --git a/src/AudioEngine.js b/src/AudioEngine.js
index 80122ab..9d37c77 100644
--- a/src/AudioEngine.js
+++ b/src/AudioEngine.js
@@ -248,12 +248,21 @@ class AudioEngine {
         log.warn('the createPlayer method is no longer available, please use createBank');
     }
 
+    /**
+     * Create an effect chain.
+     * @returns {EffectChain} chain of effects defined by this AudioEngine
+     */
     createEffectChain () {
         const effects = new EffectChain(this, this.effects);
         effects.connect(this);
         return effects;
     }
 
+    /**
+     * Create a sound bank and effect chain.
+     * @returns {SoundBank} a sound bank configured with an effect chain
+     *     defined by this AudioEngine
+     */
     createBank () {
         return new SoundBank(this, this.createEffectChain());
     }
diff --git a/src/SoundPlayer.js b/src/SoundPlayer.js
index 7cabf2d..8fa9e37 100644
--- a/src/SoundPlayer.js
+++ b/src/SoundPlayer.js
@@ -21,23 +21,75 @@ class SoundPlayer extends EventEmitter {
     constructor (audioEngine, {id, buffer}) {
         super();
 
+        /**
+         * Unique sound identifier set by AudioEngine.
+         * @type {string}
+         */
         this.id = id;
 
+        /**
+         * AudioEngine creating this sound player.
+         * @type {AudioEngine}
+         */
         this.audioEngine = audioEngine;
+
+        /**
+         * Decoded audio buffer from audio engine for playback.
+         * @type {AudioBuffer}
+         */
         this.buffer = buffer;
 
+        /**
+         * Output audio node.
+         * @type {AudioNode}
+         */
         this.outputNode = null;
+
+        /**
+         * VolumeEffect used to fade out playing sounds when stopping them.
+         * @type {VolumeEffect}
+         */
         this.volumeEffect = null;
+
+
+        /**
+         * Target engine, effect, or chain this player directly connects to.
+         * @type {AudioEngine|Effect|EffectChain}
+         */
         this.target = null;
 
+        /**
+         * Internally is the SoundPlayer initialized with at least its buffer
+         * source node and output node.
+         * @type {boolean}
+         */
         this.initialized = false;
+
+        /**
+         * Is the sound playing or starting to play?
+         * @type {boolean}
+         */
         this.isPlaying = false;
+
+        /**
+         * Timestamp sound is expected to be starting playback until. Once the
+         * future timestamp is reached the sound is considered to be playing
+         * through the audio hardware and stopping should fade out instead of
+         * cutting off playback.
+         * @type {number}
+         */
         this.startingUntil = 0;
+
+        /**
+         * Rate to play back the audio at.
+         * @type {number}
+         */
         this.playbackRate = 1;
 
-        // handleEvent is a EventTarget api for the DOM, however the web-audio-test-api we use
-        // uses an addEventListener that isn't compatable with object and requires us to pass
-        // this bound function instead
+        // handleEvent is a EventTarget api for the DOM, however the
+        // web-audio-test-api we use uses an addEventListener that isn't
+        // compatable with object and requires us to pass this bound function
+        // instead
         this.handleEvent = this.handleEvent.bind(this);
     }
 
@@ -232,14 +284,15 @@ class SoundPlayer extends EventEmitter {
             return;
         }
 
-        // always do a manual stop on a taken / volume effect fade out sound player
-        // take will emit "stop" as well as reset all of our playing statuses / remove our
-        // nodes / etc
+        // always do a manual stop on a taken / volume effect fade out sound
+        // player take will emit "stop" as well as reset all of our playing
+        // statuses / remove our nodes / etc
         const taken = this.take();
         taken.volumeEffect = new VolumeEffect(taken.audioEngine, taken, null);
 
         taken.volumeEffect.connect(taken.target);
-        // volumeEffect will recursively connect to us if it needs to, so this happens too:
+        // volumeEffect will recursively connect to us if it needs to, so this
+        // happens too:
         // taken.connect(taken.volumeEffect);
 
         taken.finished().then(() => taken.dispose());
diff --git a/src/effects/PanEffect.js b/src/effects/PanEffect.js
index 3255ee4..a0a11e6 100644
--- a/src/effects/PanEffect.js
+++ b/src/effects/PanEffect.js
@@ -20,6 +20,10 @@ class PanEffect extends Effect {
         this.channelMerger = null;
     }
 
+    /**
+     * Return the name of the effect.
+     * @type {string}
+     */
     get name () {
         return 'pan';
     }
diff --git a/src/effects/PitchEffect.js b/src/effects/PitchEffect.js
index f4d2ba6..51d581d 100644
--- a/src/effects/PitchEffect.js
+++ b/src/effects/PitchEffect.js
@@ -35,6 +35,10 @@ class PitchEffect extends Effect {
         this.ratio = 1;
     }
 
+    /**
+     * Return the name of the effect.
+     * @type {string}
+     */
     get name () {
         return 'pitch';
     }
diff --git a/src/effects/VolumeEffect.js b/src/effects/VolumeEffect.js
index 1b9942a..41d36f1 100644
--- a/src/effects/VolumeEffect.js
+++ b/src/effects/VolumeEffect.js
@@ -12,6 +12,10 @@ class VolumeEffect extends Effect {
         return 100;
     }
 
+    /**
+     * Return the name of the effect.
+     * @type {string}
+     */
     get name () {
         return 'volume';
     }