jsyn docs: various small improvements

Update build.xml to use newer versions of javadoc

8 files changed, 66 insertions, 28 deletions

diff --git a/build.xml b/build.xml
index f949f4a..d06049d 100644
--- a/build.xml
+++ b/build.xml
@@ -45,7 +45,12 @@
 
   <!-- Generate javadocs for current project into ${doc.dir} -->
   <target name="doc" depends="init" description="generate documentation">
-    <javadoc sourcepath="${src.dir}" destdir="${doc.dir}"/>
+    <javadoc
+        sourcepath="${src.dir}"
+        destdir="${doc.dir}"
+        packagenames="com.jsyn.*"
+        excludepackagenames="com.portaudio,com.jsyn.devices.jportaudio"
+    />
     <echo message = "=================================================================" />
     <echo message = "Javadocs have been generated and placed in the ${doc.dir} folder!" />
     <echo message = "=================================================================" />
diff --git a/src/com/jsyn/Synthesizer.java b/src/com/jsyn/Synthesizer.java
index 784b355..bfabb4c 100644
--- a/src/com/jsyn/Synthesizer.java
+++ b/src/com/jsyn/Synthesizer.java
@@ -47,14 +47,22 @@ public interface Synthesizer {
 
     /**
      * Starts the synthesizer using specific audio devices.
+     * <p>
+     * Note that using more than 2 channels will probably require the use of JPortAudio because
+     * JavaSound currently does not support more than two channels.
+     * JPortAudio is available at
+     * <a href="http://www.softsynth.com/jsyn/developers/download.php">http://www.softsynth.com/jsyn/developers/download.php</a>.
+     * <p>
+     * If you use more than 2 inputs or outputs then you will probably want to use {@link com.jsyn.unitgen.ChannelIn}
+     * or {@link com.jsyn.unitgen.ChannelOut}, which can be associated with any indexed channel.
      *
      * @param frameRate in Hertz
      * @param inputDeviceID obtained from an {@link AudioDeviceManager} or pass
      *            AudioDeviceManager.USE_DEFAULT_DEVICE
-     * @param numInputChannels 1 for mono, 2 for stereo, etcetera
+     * @param numInputChannels 0 for no input, 1 for mono, 2 for stereo, etcetera
      * @param ouputDeviceID obtained from an AudioDeviceManager or pass
      *            AudioDeviceManager.USE_DEFAULT_DEVICE
-     * @param numOutputChannels 1 for mono, 2 for stereo, etcetera
+     * @param numOutputChannels 0 for no output, 1 for mono, 2 for stereo, etcetera
      */
     public void start(int frameRate, int inputDeviceID, int numInputChannels, int ouputDeviceID,
             int numOutputChannels);
@@ -96,7 +104,7 @@ public interface Synthesizer {
     /**
      * Start a unit generator at the specified time. This is not needed if a unit generator's output
      * is connected to other units. Typically you only need to start units that have no outputs, for
-     * example LineOut.
+     * example LineOut or ChannelOut.
      */
     public void startUnit(UnitGenerator unit, double time);
 
@@ -181,7 +189,7 @@ public interface Synthesizer {
     public boolean isRunning();
 
     /**
-     * Add a task that will get run on the Audio Thread before it generates a new block of Audio.
+     * Add a task that will be run repeatedly on the Audio Thread before it generates every new block of Audio.
      * This task must be very quick and should not perform any blocking operations. If you are not
      * certain that you need an Audio rate task then don't use this.
      *
diff --git a/src/com/jsyn/data/FloatSample.java b/src/com/jsyn/data/FloatSample.java
index 0855786..2d8c973 100644
--- a/src/com/jsyn/data/FloatSample.java
+++ b/src/com/jsyn/data/FloatSample.java
@@ -57,7 +57,7 @@ public class FloatSample extends AudioSample implements Function {
     }
 
     /**
-     * Create an silent sample with enough memory to hold the audio data. The number of sample
+     * Create a silent sample with enough memory to hold the audio data. The number of sample
      * numbers in the array will be numFrames*channelsPerFrame.
      *
      * @param numFrames number of sample groups. A stereo frame contains 2 samples.
@@ -133,7 +133,10 @@ public class FloatSample extends AudioSample implements Function {
         buffer[index] = (float) value;
     }
 
-    /*
+    /**
+     * Interpolate between two adjacent samples.
+     * Note that this will only work for mono, single channel samples.
+     *
      * @param fractionalIndex must be >=0 and < (size-1)
      */
     public double interpolate(double fractionalIndex) {
@@ -144,6 +147,9 @@ public class FloatSample extends AudioSample implements Function {
         return ((target - source) * phase) + source;
     }
 
+    /**
+     * Note that this will only work for mono, single channel samples.
+     */
     @Override
     public double evaluate(double input) {
         // Input ranges from -1 to +1
diff --git a/src/com/jsyn/data/SequentialData.java b/src/com/jsyn/data/SequentialData.java
index c5ce2f0..0deb5c9 100644
--- a/src/com/jsyn/data/SequentialData.java
+++ b/src/com/jsyn/data/SequentialData.java
@@ -4,9 +4,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  *     http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -26,7 +26,7 @@ import com.jsyn.unitgen.VariableRateStereoReader;
 /**
  * Interface for objects that can be read and/or written by index. The index is not stored
  * internally so they can be shared by multiple readers.
- * 
+ *
  * @author Phil Burk (C) 2010 Mobileer Inc
  * @see FixedRateMonoReader
  * @see FixedRateStereoReader
@@ -38,7 +38,7 @@ import com.jsyn.unitgen.VariableRateStereoReader;
 public interface SequentialData {
     /**
      * Write a value at the given index.
-     * 
+     *
      * @param index sample index is ((frameIndex * channelsPerFrame) + channelIndex)
      * @param value the value to be written
      */
@@ -46,7 +46,7 @@ public interface SequentialData {
 
     /**
      * Read a value from the sample independently from the internal storage format.
-     * 
+     *
      * @param index sample index is ((frameIndex * channelsPerFrame) + channelIndex)
      */
 
@@ -60,7 +60,7 @@ public interface SequentialData {
     /**
      * SustainEnd value is the frame index of the frame just past the end of the loop. The number of
      * frames included in the loop is (SustainEnd - SustainBegin).
-     * 
+     *
      * @return End of sustain loop or -1 if no loop.
      */
     public int getSustainEnd();
@@ -78,7 +78,7 @@ public interface SequentialData {
     /**
      * Get rate to play the data. In an envelope this correspond to the inverse of the frame
      * duration and would vary frame to frame. For an audio sample it is 1.0.
-     * 
+     *
      * @param index
      * @param synthesisRate
      * @return rate to scale the playback speed.
diff --git a/src/com/jsyn/data/SequentialDataCommon.java b/src/com/jsyn/data/SequentialDataCommon.java
index 190cd92..5cc51df 100644
--- a/src/com/jsyn/data/SequentialDataCommon.java
+++ b/src/com/jsyn/data/SequentialDataCommon.java
@@ -4,9 +4,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  *     http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -18,7 +18,7 @@ package com.jsyn.data;
 
 /**
  * Abstract base class for envelopes and samples that adds sustain and release loops.
- * 
+ *
  * @author Phil Burk (C) 2010 Mobileer Inc
  */
 public abstract class SequentialDataCommon implements SequentialData {
@@ -85,28 +85,47 @@ public abstract class SequentialDataCommon implements SequentialData {
         return this.releaseEnd;
     }
 
+    /**
+     * Set beginning of a sustain loop. When UnitDataQueuePort.queueOn() is called,
+     * if the loop is set then the attack portion will be queued followed by this sustain
+     * region using queueLoop().
+     * The number of frames in the loop will be (SustainEnd - SustainBegin).
+     * <p>
+     * For a steady sustain level, like in an ADSR envelope, set SustainBegin and
+     * SustainEnd to the same frame.
+     * <p>
+     * For a sustain that is modulated, include two or more frames in the loop.
+     *
+     * @param sustainBegin
+    */
     public void setSustainBegin(int sustainBegin) {
         this.sustainBegin = sustainBegin;
     }
 
     /**
-     * SustainEnd value is the frame index of the frame just past the end of the loop. The number of
-     * frames included in the loop is (SustainEnd - SustainBegin).
-     * 
+     * SustainEnd value is the frame index of the frame just past the end of the loop.
+     * The number of frames included in the loop is (SustainEnd - SustainBegin).
+     *
      * @param sustainEnd
      */
     public void setSustainEnd(int sustainEnd) {
         this.sustainEnd = sustainEnd;
     }
 
+    /**
+     * The release loop behaves like the sustain loop but it is triggered
+     * by UnitDataQueuePort.queueOff().
+     *
+     * @param releaseBegin
+     */
     public void setReleaseBegin(int releaseBegin) {
         this.releaseBegin = releaseBegin;
     }
 
     /**
-     * ReleaseEnd value is the frame index of the frame just past the end of the loop. The number of
-     * frames included in the loop is (ReleaseEnd - ReleaseBegin).
-     * 
+     * ReleaseEnd value is the frame index of the frame just past the end of the loop.
+     * The number of frames included in the loop is (ReleaseEnd - ReleaseBegin).
+     *
      * @param releaseEnd
      */
 
diff --git a/src/com/jsyn/ports/UnitDataQueuePort.java b/src/com/jsyn/ports/UnitDataQueuePort.java
index f96e12a..5487589 100644
--- a/src/com/jsyn/ports/UnitDataQueuePort.java
+++ b/src/com/jsyn/ports/UnitDataQueuePort.java
@@ -361,10 +361,8 @@ public class UnitDataQueuePort extends UnitPort {
         if (queueableData.getSustainBegin() < 0) {
             // no sustain loop, handle release
             if (queueableData.getReleaseBegin() < 0) {
-                queueImmediate(queueableData, 0, queueableData.getNumFrames(), timeStamp); /*
-                                                                                            * No
-                                                                                            * loops.
-                                                                                            */
+                // No loops
+                queueImmediate(queueableData, 0, queueableData.getNumFrames(), timeStamp);
             } else {
                 queueImmediate(queueableData, 0, queueableData.getReleaseEnd(), timeStamp);
                 int size = queueableData.getReleaseEnd() - queueableData.getReleaseBegin();
diff --git a/src/com/jsyn/unitgen/ChannelIn.java b/src/com/jsyn/unitgen/ChannelIn.java
index 0d8584e..c440b4f 100644
--- a/src/com/jsyn/unitgen/ChannelIn.java
+++ b/src/com/jsyn/unitgen/ChannelIn.java
@@ -20,7 +20,7 @@ import com.jsyn.ports.UnitOutputPort;
 
 /**
  * Provides access to one specific channel of the audio input. For ChannelIn to work you must call
- * the Synthesizer start() method with numInputChannels &gt; 0.
+ * the {@link com.jsyn.Synthesizer} start() method with numInputChannels &gt; 0.
  *
  * @author Phil Burk (C) 2009 Mobileer Inc
  * @see ChannelOut
diff --git a/src/com/jsyn/unitgen/ChannelOut.java b/src/com/jsyn/unitgen/ChannelOut.java
index 89f778b..8ef0677 100644
--- a/src/com/jsyn/unitgen/ChannelOut.java
+++ b/src/com/jsyn/unitgen/ChannelOut.java
@@ -20,6 +20,8 @@ import com.jsyn.ports.UnitInputPort;
 
 /**
  * Provides access to one channel of the audio output.
+ * For more than two channels you must call
+ * the {@link com.jsyn.Synthesizer} start() method with numOutputChannels &gt; 2.
  *
  * @author Phil Burk (C) 2009 Mobileer Inc
  * @see ChannelIn