JSDoc comments

src/effects/EchoEffect.js

@@ -1,17 +1,18 @@
-/*
-
-An echo effect
-
-0 mutes the effect
-Values up to 100 set the echo feedback amount,
-increasing the time it takes the echo to fade away
-
-Clamped 0-100
-
-*/
-
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* An echo effect (aka 'delay effect' in audio terms)
+* Effect value of 0 mutes the effect
+* Values up to 100 set the echo feedback amount,
+* increasing the time it takes the echo to fade away
+* Clamped 0-100
+*/
+
+/**
+* Initialize and chain the effect
+* @constructor
+*/
 function EchoEffect () {
     Tone.Effect.call(this);
 
@@ -24,6 +25,10 @@ function EchoEffect () {
 
 Tone.extend(EchoEffect, Tone.Effect);
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+*/
 EchoEffect.prototype.set = function (val) {
     this.value = val;
 
@@ -40,10 +45,20 @@ EchoEffect.prototype.set = function (val) {
     this.delay.feedback.rampTo(feedback, 1/60);
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+*/
 EchoEffect.prototype.changeBy = function (val) {
     this.set(this.value + val);
 };
 
+/**
+* Clamp the input to a range
+* @param {number} input - the input to clamp
+* @param {number} min - the min value to clamp to
+* @param {number} max - the max value to clamp to
+*/
 EchoEffect.prototype.clamp = function (input, min, max) {
     return Math.min(Math.max(input, min), max);
 };

src/effects/FuzzEffect.js

@@ -1,17 +1,17 @@
-/*
-
-A fuzz effect
-
-Distortion
-
-the value controls the wet/dry amount
-
-Clamped 0-100
-
-*/
-
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* An fuzz effect (aka 'distortion effect' in audio terms)
+* Effect value controls the wet/dry amount:
+* 0 passes through none of the effect, 100 passes through all effect
+* Clamped 0-100
+*/
+
+/**
+* Initialize and chain the effect
+* @constructor
+*/
 function FuzzEffect () {
     Tone.Effect.call(this);
 
@@ -24,6 +24,10 @@ function FuzzEffect () {
 
 Tone.extend(FuzzEffect, Tone.Effect);
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+*/
 FuzzEffect.prototype.set = function (val) {
     this.value = val;
 
@@ -32,10 +36,19 @@ FuzzEffect.prototype.set = function (val) {
     this.distortion.wet.value = this.value / 100;
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+*/
 FuzzEffect.prototype.changeBy = function (val) {
     this.set(this.value + val);
 };
 
+/**
+* @param {number} input - the input to clamp
+* @param {number} min - the min value to clamp to
+* @param {number} max - the max value to clamp to
+*/
 FuzzEffect.prototype.clamp = function (input, min, max) {
     return Math.min(Math.max(input, min), max);
 };

src/effects/PanEffect.js

@@ -1,15 +1,17 @@
-/*
-
-A Pan effect
-
--100 puts the audio on the left channel, 0 centers it, 100 puts it on the right.
-
-Clamped -100 to 100
-
-*/
-
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* An pan effect, which moves the sound to the left or right between the speakers
+* Effect value of -100 puts the audio entirely on the left channel,
+* 0 centers it, 100 puts it on the right.
+* Clamped -100 to 100
+*/
+
+/**
+* Initialize and chain the effect
+* @constructor
+*/
 function PanEffect () {
     Tone.Effect.call(this);
 
@@ -22,6 +24,10 @@ function PanEffect () {
 
 Tone.extend(PanEffect, Tone.Effect);
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+*/
 PanEffect.prototype.set = function (val) {
     this.value = val;
 
@@ -30,10 +36,20 @@ PanEffect.prototype.set = function (val) {
     this.panner.pan.value = this.value / 100;
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+*/
 PanEffect.prototype.changeBy = function (val) {
     this.set(this.value + val);
 };
 
+/**
+* Clamp the input to a range
+* @param {number} input - the input to clamp
+* @param {number} min - the min value to clamp to
+* @param {number} max - the max value to clamp to
+*/
 PanEffect.prototype.clamp = function (input, min, max) {
     return Math.min(Math.max(input, min), max);
 };

src/effects/PitchEffect.js

@@ -1,36 +1,78 @@
-/*
-
-A Pitch effect
-
-*/
-
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* An pitch change effect, which changes the playback rate of the sound in order
+* to change its pitch: reducing the playback rate lowers the pitch, increasing the rate
+* raises the pitch. The duration of the sound is also changed.
+*
+* Changing the value of the pitch effect by 10 causes a change in pitch by 1 semitone
+* (i.e. a musical half-step, such as the difference between C and C#)
+* Changing the pitch effect by 120 changes the pitch by one octave (12 semitones)
+*
+* The value of this effect is not clamped (i.e. it is typically between -120 and 120,
+* but can be set much higher or much lower, with weird and fun results).
+* We should consider what extreme values to use for clamping it.
+*
+* Note that this effect functions differently from the other audio effects. It is
+* not part of a chain of audio nodes. Instead, it provides a way to set the playback
+* on one SoundPlayer or a group of them.
+*/
+
+/**
+* Initialize the effect
+* @constructor
+*/
 function PitchEffect () {
-    this.value = 0;
-    this.ratio = 1;
+    this.value = 0; // effect value
+    this.ratio = 1; // the playback rate ratio
 
     this.tone = new Tone();
 }
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+* @param {object} players - a dictionary of SoundPlayer objects to apply the effect to, indexed by md5
+*/
 PitchEffect.prototype.set = function (val, players) {
     this.value = val;
     this.ratio = this.getRatio(this.value);
     this.updatePlayers(players);
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+* @param {Object} players - a dictionary of SoundPlayer objects indexed by md5
+*/
 PitchEffect.prototype.changeBy = function (val, players) {
     this.set(this.value + val, players);
 };
 
+/**
+* Compute the playback ratio for an effect value.
+* The playback ratio is scaled so that a change of 10 in the effect value
+* gives a change of 1 semitone in the ratio.
+* @param {number} val - an effect value
+* @returns {number} a playback ratio
+*/
 PitchEffect.prototype.getRatio = function (val) {
     return this.tone.intervalToFrequencyRatio(val / 10);
 };
 
+/**
+* Update a sound player's playback rate using the current ratio for the effect
+* @param {Object} player - a SoundPlayer object
+*/
 PitchEffect.prototype.updatePlayer = function (player) {
     player.setPlaybackRate(this.ratio);
 };
 
+/**
+* Update a sound player's playback rate using the current ratio for the effect
+* @param {object} players - a dictionary of SoundPlayer objects to update, indexed by md5
+*/
 PitchEffect.prototype.updatePlayers = function (players) {
     if (!players) return;
 
@@ -39,7 +81,5 @@ PitchEffect.prototype.updatePlayers = function (players) {
     }
 };
 
-
-
 module.exports = PitchEffect;
 

src/effects/ReverbEffect.js

@@ -1,15 +1,17 @@
-/*
-
-A Reverb effect
-
-The value controls the wet/dry amount of the effect
-
-Clamped 0 to 100
-
-*/
-
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* A reverb effect, simulating reverberation in a room
+* Effect value controls the wet/dry amount:
+* 0 passes through none of the effect, 100 passes through all effect
+* Clamped 0 to 100
+*/
+
+/**
+* Initialize and chain the effect
+* @constructor
+*/
 function ReverbEffect () {
     Tone.Effect.call(this);
 
@@ -22,6 +24,10 @@ function ReverbEffect () {
 
 Tone.extend(ReverbEffect, Tone.Effect);
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+*/
 ReverbEffect.prototype.set = function (val) {
     this.value = val;
 
@@ -30,10 +36,20 @@ ReverbEffect.prototype.set = function (val) {
     this.reverb.wet.value = this.value / 100;
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+*/
 ReverbEffect.prototype.changeBy = function (val) {
     this.set(this.value + val);
 };
 
+/**
+* Clamp the input to a range
+* @param {number} input - the input to clamp
+* @param {number} min - the min value to clamp to
+* @param {number} max - the max value to clamp to
+*/
 ReverbEffect.prototype.clamp = function (input, min, max) {
     return Math.min(Math.max(input, min), max);
 };

src/effects/RoboticEffect.js

@@ -1,20 +1,22 @@
-/*
-
-A robot-voice effect
-
-A feedback comb filter with a short delay time creates a low-pitched buzzing
-The effect value controls the length of this delay time, changing the pitch
-
-0 mutes the effect
-
-Other values changes the pitch of the effect, in units of 10 steps per semitone
-
-Not clamped
-
-*/
 
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* A "robotic" effect that adds a low-pitched buzzing to the sound, reminiscent of the
+* voice of the daleks from Dr. Who.
+* In audio terms it is a feedback comb filter with a short delay time.
+* The effect value controls the length of this delay time, changing the pitch of the buzz
+* A value of 0 mutes the effect.
+* Other values change the pitch of the effect, in units of 10 steps per semitone.
+* The effect value is not clamped (but probably should be).
+* Exterminate.
+*/
+
+/**
+* Initialize and chain the effect
+* @constructor
+*/
 function RoboticEffect () {
     Tone.Effect.call(this);
 
@@ -28,6 +30,10 @@ function RoboticEffect () {
 
 Tone.extend(RoboticEffect, Tone.Effect);
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+*/
 RoboticEffect.prototype.set = function (val) {
     this.value = val;
 
@@ -43,13 +49,22 @@ RoboticEffect.prototype.set = function (val) {
     this.feedbackCombFilter.delayTime.rampTo(time, 1/60);
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+*/
 RoboticEffect.prototype.changeBy = function (val) {
     this.set(this.value + val);
 };
 
+/**
+* Compute the delay time for an effect value.
+* Convert the effect value to a musical note (in units of 10 per semitone),
+* and return the period (single cycle duration) of the frequency of that note.
+* @param {number} val - the effect value
+* @returns {number} a delay time in seconds
+*/
 RoboticEffect.prototype._delayTimeForValue = function (val) {
-    // convert effect setting range, typically 0-100 but can be outside that,
-    // to a musical note, and return the period of the frequency of that note
     var midiNote = ((val - 100) / 10) + 36;
     var freq = Tone.Frequency(midiNote, 'midi').eval();
     return 1 / freq;

src/effects/WobbleEffect.js

@@ -1,16 +1,21 @@
-/*
-
-A wobble effect
-
-A low frequency oscillator (LFO) controls a gain node
-This creates an effect like tremolo
-
-Clamped 0 to 100
-
-*/
-
 var Tone = require('tone');
 
+/**
+* @fileoverview
+* A wobble effect. In audio terms, it sounds like tremolo.
+* It is implemented using a low frequency oscillator (LFO) controlling
+* a gain node, which causes the loudness of the signal passing through
+* to increase and decrease rapidly.
+* Effect value controls the wet/dry amount:
+* 0 passes through none of the effect, 100 passes through all effect
+* Effect value also controls the frequency of the LFO.
+* Clamped 0 to 100
+*/
+
+/**
+* Initialize and chain the effect
+* @constructor
+*/
 function WobbleEffect () {
     Tone.Effect.call(this);
 
@@ -25,6 +30,10 @@ function WobbleEffect () {
 
 Tone.extend(WobbleEffect, Tone.Effect);
 
+/**
+* Set the effect value
+* @param {number} val - the new value to set the effect to
+*/
 WobbleEffect.prototype.set = function (val) {
     this.value = val;
 
@@ -35,10 +44,20 @@ WobbleEffect.prototype.set = function (val) {
     this.wobbleLFO.frequency.rampTo(this.value / 10, 1/60);
 };
 
+/**
+* Change the effect value
+* @param {number} val - the value to change the effect by
+*/
 WobbleEffect.prototype.changeBy = function (val) {
     this.set(this.value + val);
 };
 
+/**
+* Clamp the input to a range
+* @param {number} input - the input to clamp
+* @param {number} min - the min value to clamp to
+* @param {number} max - the max value to clamp to
+*/
 WobbleEffect.prototype.clamp = function (input, min, max) {
     return Math.min(Math.max(input, min), max);
 };