added missing javadoc comments

git-svn-id: file:///home/mbien/NetBeansProjects/JOGAMP/joal-sync/git-svn/../svn-server-sync/joal/trunk@26 03bf7f67-59de-4072-a415-9a990d468a3f

7 files changed, 198 insertions, 152 deletions

diff --git a/src/java/net/java/games/sound3d/AudioSystem3D.java b/src/java/net/java/games/sound3d/AudioSystem3D.java
index 80eac7c..b356b6b 100644
--- a/src/java/net/java/games/sound3d/AudioSystem3D.java
+++ b/src/java/net/java/games/sound3d/AudioSystem3D.java
@@ -45,7 +45,8 @@ import javax.sound.sampled.UnsupportedAudioFileException;
 
 
 /**
- * DOCUMENT ME!
+ * The AudioSystem3D class provides a set of methods for creating and
+ * manipulating a 3D audio environment.
  *
  * @author Athomas Goldberg
  */
@@ -55,7 +56,8 @@ public class AudioSystem3D {
     private static Listener listener;
 
     /**
-     * DOCUMENT ME!
+     * Iniitalize the Sound3D environment. This must be called before
+     * other methods in the class can be used.
      */
     public static void init() {
         ALFactory.initialize();
@@ -64,24 +66,23 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Creates a new Sound3D Context for a specified device.
      *
-     * @param device DOCUMENT ME!
+     * @param device The device the Context is being created for.
      *
-     * @return DOCUMENT ME!
+     * @return The new Sound3D context.
      */
     public static Context createContext(Device device) {
         Context result = null;
         ALC.Context realContext = alc.alcCreateContext(device.realDevice, null);
         result = new Context(alc, realContext, device);
-
         return result;
     }
 
     /**
-     * DOCUMENT ME!
+     * Makes the specified context the current context.
      *
-     * @param context DOCUMENT ME!
+     * @param context the context to make current.
      */
     public static void makeContextCurrent(Context context) {
         ALC.Context realContext = null;
@@ -94,11 +95,13 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Opens the specifified audio device. 
      *
-     * @param deviceName DOCUMENT ME!
+     * @param deviceName The specified device name, On windows this will be 
+     * DirectSound3D. We will be automating device discovery in upcoming versions
+     * of this class.
      *
-     * @return DOCUMENT ME!
+     * @return The device described by the specifed name.
      */
     public static Device openDevice(String deviceName) {
         Device result = null;
@@ -109,11 +112,11 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Generate an array of Sound3D buffers.
      *
-     * @param numBuffers DOCUMENT ME!
+     * @param numBuffers The number of Sound3D buffers to generate.
      *
-     * @return DOCUMENT ME!
+     * @return an array of (initially enpty) Sound3D buffers.
      */
     public static Buffer[] generateBuffers(int numBuffers) {
         Buffer[] result = new Buffer[numBuffers];
@@ -128,14 +131,17 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Loads a Sound3D buffer with the specified audio file.
      *
-     * @param filename DOCUMENT ME!
+     * @param filename the name of the file to load.
      *
-     * @return DOCUMENT ME!
+     * @return a new Sound3D buffer containing the audio data from the
+     * specified file.
      *
-     * @throws IOException DOCUMENT ME!
-     * @throws UnsupportedAudioFileException DOCUMENT ME!
+     * @throws IOException If the file cannot be found or some other IO error
+     * occurs. 
+     * @throws UnsupportedAudioFileException If the format of the sudio data is
+     * not supported
      */
     public static Buffer loadBuffer(String filename)
         throws IOException, UnsupportedAudioFileException {
@@ -150,14 +156,18 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Loads a Sound3D Source with the specified audio file. This is
+     * functionally equivelant to generateSource(loadBuffer(fileName));
      *
-     * @param filename DOCUMENT ME!
+     * @param filename the name of the file to load.
      *
-     * @return DOCUMENT ME!
+     * @return a new Sound3D Source containing the audio data from the
+     * specified file.
      *
-     * @throws IOException DOCUMENT ME!
-     * @throws UnsupportedAudioFileException DOCUMENT ME!
+     * @throws IOException If the file cannot be found or some other IO error
+     * occurs. 
+     * @throws UnsupportedAudioFileException If the format of the sudio data is
+     * not supported
      */
     public static Source loadSource(String filename)
         throws IOException, UnsupportedAudioFileException {
@@ -167,11 +177,11 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Generates a set of uninitialized Source3D sources
      *
-     * @param numSources DOCUMENT ME!
+     * @param numSources the number of Sound3D sources to generate.
      *
-     * @return DOCUMENT ME!
+     * @return an array of uninitialized sources.
      */
     public static Source[] generateSources(int numSources) {
         Source[] result = new Source[numSources];
@@ -186,11 +196,11 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Generate a Sound3D source from an initialized Buffer.
      *
-     * @param buff DOCUMENT ME!
+     * @param buff The buffer to generate the source from.
      *
-     * @return DOCUMENT ME!
+     * @return the newly generated Source.
      */
     public static Source generateSource(Buffer buff) {
         Source result = null;
@@ -202,9 +212,9 @@ public class AudioSystem3D {
     }
 
     /**
-     * DOCUMENT ME!
+     * Get the listener object associated with this Sound3D environment.
      *
-     * @return DOCUMENT ME!
+     * @return The listener object.
      */
     public static Listener getListener() {
         if (listener == null) {
diff --git a/src/java/net/java/games/sound3d/Buffer.java b/src/java/net/java/games/sound3d/Buffer.java
index c94915b..5afbc40 100644
--- a/src/java/net/java/games/sound3d/Buffer.java
+++ b/src/java/net/java/games/sound3d/Buffer.java
@@ -1,139 +1,135 @@
 /**
-* Copyright (c) 2003 Sun Microsystems, Inc. All  Rights Reserved.
-*
-* Redistribution and use in source and binary forms, with or without
-* modification, are permitted provided that the following conditions are met:
-*
-* -Redistribution of source code must retain the above copyright notice, 
-* this list of conditions and the following disclaimer.
-*
-* -Redistribution in binary form must reproduce the above copyright notice, 
-* this list of conditions and the following disclaimer in the documentation
-* and/or other materials provided with the distribution.
-*
-* Neither the name of Sun Microsystems, Inc. or the names of contributors may 
-* be used to endorse or promote products derived from this software without 
-* specific prior written permission.
-* 
-* This software is provided "AS IS," without a warranty of any kind.
-* ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING
-* ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
-* NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MIDROSYSTEMS, INC. ("SUN") AND ITS
-* LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A
-* RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
-* IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT
-* OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR
-* PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
-* ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS
-* BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-*
-* You acknowledge that this software is not designed or intended for use in the
-* design, construction, operation or maintenance of any nuclear facility.
-*/
-
+ * Copyright (c) 2003 Sun Microsystems, Inc. All  Rights Reserved.
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * -Redistribution of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer. -Redistribution in
+ * binary form must reproduce the above copyright notice,  this list of
+ * conditions and the following disclaimer in the documentation and/or other
+ * materials provided with the distribution. Neither the name of Sun
+ * Microsystems, Inc. or the names of contributors may  be used to endorse or
+ * promote products derived from this software without  specific prior written
+ * permission.  This software is provided "AS IS," without a warranty of any
+ * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
+ * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+ * PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MIDROSYSTEMS, INC.
+ * ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
+ * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR
+ * ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY
+ * LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
+ * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
+ * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
+ * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGES. You acknowledge that this software is not
+ * designed or intended for use in the design, construction, operation or
+ * maintenance of any nuclear facility.
+ */
 package net.java.games.sound3d;
 
-import java.nio.ByteBuffer;
-
 import net.java.games.joal.AL;
 
+import java.nio.ByteBuffer;
+
 
 /**
- * DOCUMENT ME!
+ * The Sound3D Buffer is a container for audio data used in the Sound3D
+ * environment.
  *
  * @author Athomas Goldberg
  */
 public class Buffer {
-    //DOCUMENT ME!
-    public final static int FORMAT_MONO8 = AL.AL_FORMAT_MONO8;
+     public final static int FORMAT_MONO8 = AL.AL_FORMAT_MONO8;
 
-    //DOCUMENT ME!
     public final static int FORMAT_MONO16 = AL.AL_FORMAT_MONO16;
 
-    //DOCUMENT ME!
     public final static int FORMAT_STEREO8 = AL.AL_FORMAT_STEREO8;
 
-    //DOCUMENT ME!
     public final static int FORMAT_STEREO16 = AL.AL_FORMAT_STEREO16;
-    final int bufferName;
+    final int bufferID;
     private ByteBuffer data;
     private boolean isConfigured = false;
     private final AL al;
 
-    Buffer(AL al, int bufferName) {
-        this.bufferName = bufferName;
+    Buffer(AL al, int bufferID) {
+        this.bufferID = bufferID;
         this.al = al;
     }
 
     /**
-     * DOCUMENT ME!
+     * Configure the Sound3D buffer
      *
-     * @param data DOCUMENT ME!
-     * @param format DOCUMENT ME!
-     * @param freq DOCUMENT ME!
+     * @param data the raw audio data
+     * @param format the format of the data: <code>FORMAT_MONO8, FORMAT_MONO16,
+     *        FORMAT_STEREO8</code> and <code>FORMAT_STEREO16</code>
+     * @param freq the frequency of the data
      */
     public void configure(ByteBuffer data, int format, int freq) {
         if (!isConfigured) {
-            al.alBufferData(bufferName, format, data, data.capacity(), freq);
+            al.alBufferData(bufferID, format, data, data.capacity(), freq);
         }
     }
 
     /**
-     * DOCUMENT ME!
+     * Delete this buffer, and free its resources.
      */
     public void delete() {
         data = null;
-        al.alDeleteBuffers(1, new int[] { bufferName });
+        al.alDeleteBuffers(1, new int[] { bufferID });
     }
 
     /**
-     * DOCUMENT ME!
+     * Get the bit-depth of the data, (8 or 16)
      *
+     * @return the bit-depth of the data
      */
     public int getBitDepth() {
         int[] i = new int[1];
-        al.alGetBufferi(bufferName, AL.AL_BITS, i);
+        al.alGetBufferi(bufferID, AL.AL_BITS, i);
 
         return i[0];
     }
 
     /**
-     * DOCUMENT ME!
+     * Get the number of channels of the data (1-Mono, 2-Stereo)
      *
+     * @return the number of audio channels.
      */
     public int getNumChannels() {
         int[] i = new int[1];
-        al.alGetBufferi(bufferName, AL.AL_CHANNELS, i);
+        al.alGetBufferi(bufferID, AL.AL_CHANNELS, i);
 
         return i[0];
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the raw data contained in this buffer.
      *
+     * @return the raw buffer data.
      */
     public ByteBuffer getData() {
         return data;
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the audio frequency of the data contained in this buffer.
      *
+     * @return the frequency of the data
      */
     public int getFrequency() {
         int[] i = new int[1];
-        al.alGetBufferi(bufferName, AL.AL_FREQUENCY, i);
+        al.alGetBufferi(bufferID, AL.AL_FREQUENCY, i);
 
         return i[0];
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the size (in bytes) of the raw data containe in this buffer.
      *
+     * @return the size of the data.
      */
     public int getSize() {
         int[] i = new int[1];
-        al.alGetBufferi(bufferName, AL.AL_SIZE, i);
+        al.alGetBufferi(bufferID, AL.AL_SIZE, i);
 
         return i[0];
     }
diff --git a/src/java/net/java/games/sound3d/Context.java b/src/java/net/java/games/sound3d/Context.java
index 5215810..00d7178 100644
--- a/src/java/net/java/games/sound3d/Context.java
+++ b/src/java/net/java/games/sound3d/Context.java
@@ -35,29 +35,42 @@ package net.java.games.sound3d;
 
 import net.java.games.joal.ALC;
 
+
 /**
- * @author Athomas Goldberg
+ * This class provides a Sound3D Context associated with a specified device.
  *
+ * @author Athomas Goldberg
  */
 public class Context {
-	private final ALC alc;
-	final ALC.Context realContext;
+    private final ALC alc;
+    final ALC.Context realContext;
     final Device device;
-	
-	Context(ALC alc, ALC.Context realContext, Device device) {
-		this.alc = alc;
-		this.realContext = realContext;
+
+    Context(ALC alc, ALC.Context realContext, Device device) {
+        this.alc = alc;
+        this.realContext = realContext;
         this.device = device;
-	}
-	
-	public void suspend() {
-		alc.alcSuspendContext(realContext);		
-	}
-	
-	public void destroy() {
-		alc.alcDestroyContext(realContext);
-	}
-    
+    }
+
+    /**
+     * Suspend this context
+     */
+    public void suspend() {
+        alc.alcSuspendContext(realContext);
+    }
+
+    /**
+     * destroys this conteext freeing its resources.
+     */
+    public void destroy() {
+        alc.alcDestroyContext(realContext);
+    }
+
+    /**
+     * Gets the device associated with this context.
+     *
+     * @return the device associated with this context. 
+     */
     public Device getDevice() {
         return device;
     }
diff --git a/src/java/net/java/games/sound3d/Device.java b/src/java/net/java/games/sound3d/Device.java
index 5973df3..44879a3 100644
--- a/src/java/net/java/games/sound3d/Device.java
+++ b/src/java/net/java/games/sound3d/Device.java
@@ -35,20 +35,25 @@ package net.java.games.sound3d;
 
 import net.java.games.joal.ALC;
 
+
 /**
- * @author Athomas Goldberg
+ * This class provides a handle to a specific audio device.
  *
+ * @author Athomas Goldberg
  */
 public class Device {
-	private final ALC alc;
-	final ALC.Device realDevice;
-	
-	Device(ALC alc, ALC.Device realDevice) {
-		this.alc = alc;
-		this.realDevice = realDevice;
-	}
-	
-	public void close() {
-		alc.alcCloseDevice(realDevice);
-	}
+    private final ALC alc;
+    final ALC.Device realDevice;
+
+    Device(ALC alc, ALC.Device realDevice) {
+        this.alc = alc;
+        this.realDevice = realDevice;
+    }
+
+    /**
+     * closes the device, freeing its resources.
+     */
+    public void close() {
+        alc.alcCloseDevice(realDevice);
+    }
 }
diff --git a/src/java/net/java/games/sound3d/Listener.java b/src/java/net/java/games/sound3d/Listener.java
index e3509dc..d80c8d0 100644
--- a/src/java/net/java/games/sound3d/Listener.java
+++ b/src/java/net/java/games/sound3d/Listener.java
@@ -37,7 +37,9 @@ import net.java.games.joal.AL;
 
 
 /**
- * DOCUMENT ME!
+ * This class represents the human listener in the Sound3D environment. It 
+ * provides methods for controlling the position, orientation as well as other
+ * properties associated with the listener.
  *
  * @author Athomas Goldberg
  */
@@ -49,18 +51,20 @@ public class Listener {
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the Gain, or volume of the audio in the environment relative to the
+     * listener
      *
-     * @param gain DOCUMENT ME!
+     * @param gain the gain, or volume
      */
     public void setGain(float gain) {
         al.alListenerf(AL.AL_GAIN, gain);
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the value of the gain, or volume of the audio in the environment
+     * relative to the listener.
      *
-     * @return DOCUMENT ME!
+     * @return the gain value.
      */
     public float getGain() {
         float[] f = new float[1];
@@ -70,29 +74,37 @@ public class Listener {
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the position in (x-y-z coordinates) of the Listener in the Sound3D
+     * environment.
      *
-     * @param x DOCUMENT ME!
-     * @param y DOCUMENT ME!
-     * @param z DOCUMENT ME!
+     * @param x The position of the listener along the X-axis in the Sound3D
+     * environment
+     * @param y The position of the listener along the Y-axis in the Sound3D
+     * environment
+     * @param z The position of the listener along the Z-axis in the Sound3D
+     * environment
      */
     public void setPosition(float x, float y, float z) {
         al.alListener3f(AL.AL_POSITION, x, y, z);
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the position in (x-y-z coordinates) of the Listener in the Sound3D
+     * environment.
      *
-     * @param position DOCUMENT ME!
+     * @param position a Vec3f object containing the x,y and z coordinates of 
+     * Listener.
      */
     public void setPosition(Vec3f position) {
         al.alListener3f(AL.AL_POSITION, position.v1, position.v2, position.v3);
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the position in (x-y-z coordinates) of the Listener in the Sound3D
+     * environment.
      *
-     * @return DOCUMENT ME!
+     * @return a Vec3f object containing the x,y and z coordinates of 
+     * Listener.
      */
     public Vec3f getPosition() {
         Vec3f result = null;
@@ -104,18 +116,22 @@ public class Listener {
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the velocity in (x-y-z coordinates) of the Listener in the Sound3D
+     * environment. Used in determining doppler shift.
      *
-     * @param velocity DOCUMENT ME!
+     * @param velocity a Vec3f object containing the velicity in
+     * x,y and z coordinates of Listener.
      */
     public void setVelocity(Vec3f velocity) {
         al.alListener3f(AL.AL_VELOCITY, velocity.v1, velocity.v2, velocity.v3);
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the velocity in (x-y-z coordinates) of the Listener in the Sound3D
+     * environment. Used in determining doppler shift.
      *
-     * @return DOCUMENT ME!
+     * @return a Vec3f object containing the velicity in
+     * x,y and z coordinates of Listener.
      */
     public Vec3f getVelocity() {
         Vec3f result = null;
@@ -127,23 +143,29 @@ public class Listener {
     }
 
     /**
-     * DOCUMENT ME!
+     * Sets the orientation of the Listener in the Sound3D environment. 
+     * Orientation is expressed as "up" and "at" vectors. 
      *
-     * @param orientation DOCUMENT ME!
+     * @param orientation The first 3 elements of the array should contain
+     * the x,y,z up-vector, the second 3 elements should contain the x,z,z
+     * look-at vector.
      */
     public void setOrientation(float[] orientation) {
         al.alListenerfv(AL.AL_ORIENTATION, orientation);
     }
 
     /**
-     * DOCUMENT ME!
+     * Gets the orientation of the Listener in the Sound3D environment. 
+     * Orientation is expressed as "up" and "at" vectors. 
      *
-     * @return DOCUMENT ME!
+     * @return an array containing the orientation of the listener.
+     * The first 3 elements of the array contain
+     * the x,y,z up-vector, the second 3 elements contain the x,z,z
+     * look-at vector.
      */
     public float[] getOrientation() {
         float[] tmp = new float[6];
         al.alGetListenerfv(AL.AL_ORIENTATION, tmp);
-
         return tmp;
     }
 }
diff --git a/src/java/net/java/games/sound3d/Source.java b/src/java/net/java/games/sound3d/Source.java
index a6cfd04..37dfbb8 100644
--- a/src/java/net/java/games/sound3d/Source.java
+++ b/src/java/net/java/games/sound3d/Source.java
@@ -436,7 +436,7 @@ public final class Source {
      * @param buffer DOCUMENT ME!
      */
     public void setBuffer(Buffer buffer) {
-        al.alSourcei(sourceName, AL.AL_BUFFER, buffer.bufferName);
+        al.alSourcei(sourceName, AL.AL_BUFFER, buffer.bufferID);
         this.buffer = buffer;
     }
 
@@ -459,7 +459,7 @@ public final class Source {
         int[] arr = new int[numBuffers];
 
         for (int i = 0; i < numBuffers; i++) {
-            arr[i] = buffers[i].bufferName;
+            arr[i] = buffers[i].bufferID;
         }
 
         al.alSourceQueueBuffers(sourceName, numBuffers, arr);
@@ -475,7 +475,7 @@ public final class Source {
         int[] arr = new int[numBuffers];
 
         for (int i = 0; i < numBuffers; i++) {
-            arr[i] = buffers[i].bufferName;
+            arr[i] = buffers[i].bufferID;
         }
 
         al.alSourceUnqueueBuffers(sourceName, numBuffers, arr);
diff --git a/src/java/net/java/games/sound3d/Vec3f.java b/src/java/net/java/games/sound3d/Vec3f.java
index a97c304..f6f494b 100644
--- a/src/java/net/java/games/sound3d/Vec3f.java
+++ b/src/java/net/java/games/sound3d/Vec3f.java
@@ -34,26 +34,26 @@
 package net.java.games.sound3d;
 
 /**
- * DOCUMENT ME!
+ * A onvenience class representing a 3-element float vector
  *
  * @author Athomas Goldberg
  */
 public final class Vec3f {
-    //DOCUMENT ME!
+    /** the first element in the vector */
     public final float v1;
 
-    //DOCUMENT ME!
+    /** the first element in the vector */
     public final float v2;
 
-    //DOCUMENT ME!
+    /** the first element in the vector */
     public final float v3;
 
     /**
      * Creates a new Vec3f object.
      *
-     * @param v1 DOCUMENT ME!
-     * @param v2 DOCUMENT ME!
-     * @param v3 DOCUMENT ME!
+     * @param v1 the first element in the vector
+     * @param v2 the second element in the vector
+     * @param v3 the third element in the vector
      */
     public Vec3f(float v1, float v2, float v3) {
         this.v1 = v1;