Merge branch 'web-reference-documentation'

kevinstadler · kevinstadler · commit d4e54398a783 · 2023-09-06T19:35:55.000+02:00
diff --git a/src/processing/sound/Analyzer.java b/src/processing/sound/Analyzer.java
@@ -4,6 +4,10 @@
 
 import processing.core.PApplet;
 
+/**
+ * Common superclass of all audio analysis classes
+ * @webref Analysis
+ */
 abstract class Analyzer {
 
 	protected SoundObject input;
@@ -16,6 +20,7 @@ protected Analyzer(PApplet parent) {
 	 * Define the audio input for the analyzer.
 	 * 
 	 * @param input The input sound source
+	 * @webref Analysis:Analyzer
 	 **/
 	public void input(SoundObject input) {
 		if (this.input == input) {
diff --git a/src/processing/sound/AudioIn.java b/src/processing/sound/AudioIn.java
@@ -88,8 +88,6 @@ public void play(float amp, float add) {
 	 * @param amp
 	 *            the volume to grab the input at as a value from 0.0 (complete
 	 *            silence) to 1.0 (full volume)
-	 * @param add
-	 *            offset the audio input by the given value
 	 * @param pos
 	 *            pan the audio input in a stereo panorama. Allowed values are
 	 *            between -1.0 (left) and 1.0 (right)
@@ -136,22 +134,34 @@ public void start(float amp, float add, float pos) {
 	}
 
 	/**
-	 * Sets amplitude, add and pan position with one method.
+	 * Set amplitude and pan position with one method.
 	 * 
 	 * @webref I/O:AudioIn
-	 * @webBrief Sets amplitude, add and pan position with one method.
 	 * @param amp
 	 *            the volume to grab the input at as a value from 0.0 (complete
 	 *            silence) to 1.0 (full volume)
-	 * @param add
-	 *            offset the audio input by the given value
 	 * @param pos
 	 *            pan the audio input in a stereo panorama. Allowed values are
 	 *            between -1.0 (left) and 1.0 (right)
 	 **/
+	public void set(float amp, float pos) {
+		this.amp(amp);
+		this.pan(pos);
+	}
+
 	public void set(float amp, float add, float pos) {
 		this.amp(amp);
 		this.add(add);
 		this.pan(pos);
 	}
+
+	/**
+	 * Stop capturing sound from this audio input.
+	 *
+	 * @webref I/O:AudioIn
+	 **/
+	public void stop() {
+		super.stop();
+	}
+
 }
diff --git a/src/processing/sound/Effect.java b/src/processing/sound/Effect.java
@@ -11,6 +11,7 @@
 
 /**
  * For advanced users: common superclass of all effect types
+ * @webref Effects
  */
 // helper class for applying the same effect (with the same parameters) on two channels.
 // a basic design question is what to do if the same effect is applied to several different
@@ -53,7 +54,7 @@ public boolean isProcessing() {
 	/**
 	 * Start the effect.
 	 * @param input Input sound source
-	 * @webref Effects
+	 * @webref Effects:Effect
 	 */
 	public void process(SoundObject input) {
 		if (this.inputs.add(input)) {
@@ -66,7 +67,7 @@ public void process(SoundObject input) {
 
 	/**
 	 * Stop the effect.
-	 * @webref Effects
+	 * @webref Effects:Effect
 	 */
 	public void stop() {
 		if (this.inputs.isEmpty()) {
diff --git a/src/processing/sound/Env.java b/src/processing/sound/Env.java
@@ -20,7 +20,7 @@ public Env(PApplet parent) {
 
 	/**
 	* Triggers the envelope.
-	* @webref Envelopes:Env
+	* @webref Envelopes
 	* @webBrief Triggers the envelope.
 	* @param input Input sound source
 	* @param attackTime Attack time value as a float.
diff --git a/src/processing/sound/FFT.java b/src/processing/sound/FFT.java
@@ -54,20 +54,13 @@ protected void setInput(UnitOutputPort input) {
 		this.fft.start();
 	}
 
-	/**
-	 * Calculates the current frequency spectrum from the input source, writes it
-	 * into this FFT's `spectrum` array, and returns it.
-	 *
-	 * @return the current frequency spectrum of the input source. The array has as
-	 *         many elements as this FFT analyzer's number of frequency bands
-	 * @webref Analysis:FFT
-	 */
 	public float[] analyze() {
 		return this.analyze(this.spectrum);
 	}
 
 	/**
-	 * Calculates the current frequency spectrum and returns it as an array with as many elements as frequency bands.
+	 * Calculates the current frequency spectrum from the input source and returns
+	 * it as an array with as many elements as frequency bands.
 	 *
 	 * @param value
 	 *            an array with as many elements as this FFT analyzer's number of
diff --git a/src/processing/sound/Noise.java b/src/processing/sound/Noise.java
@@ -6,7 +6,8 @@
 import processing.core.PApplet;
 
 /**
- * For advanced users: common superclass of all noise generators
+ * Common superclass of all noise generators
+ * @webref Noise
  */
 public abstract class Noise<JSynNoise extends UnitGenerator> extends SoundObject {
 
@@ -23,6 +24,12 @@ public void play(float amp) {
 		this.play();
 	}
 
+	/**
+	 * Starts the noise
+	 * @webref Noise:Noise
+	 * @param amp The amplitude of the noise as a value between 0.0 and 1.0.
+	 * @param pos The panoramic position of the noise as a float from -1.0 to 1.0.
+	 **/
 	public void play(float amp, float pos) {
 		this.pan(pos);
 		this.play(amp);
@@ -33,9 +40,32 @@ public void play(float amp, float add, float pos) {
 		this.play();
 	}
 
+	/**
+	 * Set the amplitude and panoramic position with one method.
+	 * @webref Noise:Noise
+	 * @param amp The amplitude of the noise as a value between 0.0 and 1.0.
+	 * @param pos The panoramic position of the noise as a float from -1.0 to 1.0.
+	 **/
+	public void set(float amp, float pos) {
+		this.amp(amp);
+		this.pan(pos);
+	}
+
+	/**
+	 * @deprecated
+	 */
 	public void set(float amp, float add, float pos) {
 		this.amp(amp);
 		this.add(add);
 		this.pan(pos);
 	}
+
+	/**
+	 * Stop the noise from playing back
+	 * @webref Noise:Noise
+	 */
+	public void stop() {
+		super.stop();
+	}
+
 }
diff --git a/src/processing/sound/Oscillator.java b/src/processing/sound/Oscillator.java
@@ -69,10 +69,21 @@ public void set(float freq, float amp, float pos) {
 		this.pan(pos);
 	}
 
+	/**
+	 * @deprecated
+	 */
 	public void set(float freq, float amp, float add, float pos) {
 		this.freq(freq);
 		this.amp(amp);
 		this.add(add);
 		this.pan(pos);
 	}
+
+	/**
+	 * Stop the oscillator from playing back
+	 * @webref Oscillators:Oscillator
+	 */
+	public void stop() {
+		super.stop();
+	}
 }
diff --git a/src/processing/sound/SoundObject.java b/src/processing/sound/SoundObject.java
@@ -8,6 +8,7 @@
 /**
  * For advanced users: common superclass of all sound sources (oscillators,
  * noise, audio samples and even AudioIn).
+ * @webref SoundObject
  */
 // Subclasses need to assign the 'amplitude' port, and also initiate a
 // JSynCircuit (which effects can be plugged into) with an appropriate
@@ -53,6 +54,7 @@ public void add(float add) {
 	 * @param amp
 	 *            A float value between 0.0 (complete silence) and 1.0 (full volume)
 	 *            controlling the amplitude/volume of this sound.
+	 * @webref SoundObject:SoundObject
 	 **/
 	public void amp(float amp) {
 		if (Engine.checkAmp(amp)) {
@@ -79,6 +81,7 @@ public boolean isPlaying() {
 	 * @param pos
 	 *            The panoramic position of this sound unit as a float from -1.0
 	 *            (left) to 1.0 (right).
+	 * @webref SoundObject:SoundObject
 	 **/
 	public void pan(float pos) {
 		if (this.circuit.processor == null) {
@@ -89,8 +92,7 @@ public void pan(float pos) {
 	}
 
 	/**
-	 * Start the generator
-	 *
+	 * Starts the generator
 	 **/
 	public void play() {
 		// TODO print info message if it's already playing?
@@ -104,7 +106,9 @@ public void play() {
 	}
 
 	/**
-	 * Stop the generator
+	 * Stops this sound from playing back.
+	 *
+	 * @webref SoundObject:SoundObject
 	 **/
 	public void stop() {
 		this.isPlaying = false;
