Mention typical range of sample values in documentation (closes #75)

kevinstadler · kevinstadler · commit 6184e8dc16fc · 2023-10-03T13:34:30.000+02:00
diff --git a/src/processing/sound/AudioSample.java b/src/processing/sound/AudioSample.java
@@ -51,11 +51,17 @@ public AudioSample(PApplet parent, int frames, boolean stereo) {
 	 *            typically use "this"
 	 * @param frames
 	 *            the desired number of frames for this audiosample
-	 * @param frameRate
-	 *            the underlying frame rate of the sample (default: 44100)
+	 * @param data
+	 *            an array of float values to be used as this audiosample's sound
+	 *            data. The audiosample will consequently have as many frames as the
+	 *            length of the given array. To match the default amplitude of 
+	 *            other sound generators, the sample values should be in the range 
+	 *            <code>[-0.5, 0.5]</code>
 	 * @param stereo
 	 *            whether to treat the audiosample as 2-channel (stereo) or not
-	 *            (default: false)
+	 *            (default: <code>false</code>)
+	 * @param frameRate
+	 *            the underlying frame rate of the sample (default: 44100)
 	 * @webref Sampling:AudioSample
 	 * @webBrief Allocate a new audiosample buffer with the given number of frames.
 	 */
@@ -74,12 +80,6 @@ public AudioSample(PApplet parent, int frames, int frameRate) {
 	// duration)?
 	// risk of accidental overloading through int/float, but could be interesting..
 
-	/**
-	 * @param data
-	 *            an array of float values to be used as this audiosample's sound
-	 *            data. The audiosample will consequently have as many frames as the
-	 *            length of the given array.
-	 */
 	public AudioSample(PApplet parent, float[] data) {
 		this(parent, data, false);
 	}
diff --git a/src/processing/sound/Waveform.java b/src/processing/sound/Waveform.java
@@ -9,12 +9,15 @@
 /**
  * This is a Waveform analyzer. It returns the waveform of an 
  * audio stream the moment it is queried with the <b>analyze()</b>
- * method.
+ * method.<br/>
+ * Note that by default all sound generators (including microphone capture from
+ * <code>AudioIn</code>) have an amplitude of 1, which means that the values of 
+ * their waveform will be numbers in the range <code>[-0.5, 0.5]</code>.
  * 
  * @author icalvin102
  * 
  * @webref Analysis:Waveform
- * @webBrief This is a Waveform analyzer.
+ * @webBrief Inspects the underlying soundwave of an audio signal.
  **/
 public class Waveform extends Analyzer {
 
