Added OpenAL specification to javadoc

src/java/org/lwjgl/openal/AL.java

@@ -33,7 +33,7 @@ package org.lwjgl.openal;
 
 /**
  * $Id$
- *
+ * <br>
  * This is the OpenAL class. It extends the latest core.
  *
  * @author Brian Matzon <brian@matzon.dk>

src/java/org/lwjgl/openal/ALC.java

@@ -35,9 +35,29 @@ import java.nio.Buffer;
 
 /**
  * $Id$
- *
+ * 
+ * <p>
  * This is the context class for OpenAL. This class implements functions
  * in alc.h
+ * </p>
+ * 
+ * <p>
+ * ALC introduces the notion of a Device. A Device can be, depending on the
+ * implementation, a hardware device, or a daemon/OS service/actual server. This
+ * mechanism also permits different drivers (and hardware) to coexist within the same
+ * system, as well as allowing several applications to share system resources for audio,
+ * including a single hardware output device. The details are left to the
+ * implementation, which has to map the available backends to unique device
+ * specifiers (represented as strings).
+ * </p>
+ * 
+ * <p>
+ * <b>NOTE:</b><br>
+ * The LWJGL implementation of OpenAL does not expose the device, nor the context.
+ * Whenever <code>AL</code> is created using the <code>create</code> method, an underlying
+ * device and context is created. Thus more advanced usage of multiple contexts and/or devices
+ * are not possible. The above mentioned features are very rarely used in games.
+ * </p>
  *
  * @author Brian Matzon <brian@matzon.dk>
  * @version $Revision$
@@ -58,17 +78,39 @@ public class ALC {
 	/** Errors: No Error */
 	public static final int ALC_NO_ERROR = ALC_FALSE;
 
+  /** Major version query. */
 	public static final int ALC_MAJOR_VERSION = 0x1000;
+  
+  /** Minor version query. */
 	public static final int ALC_MINOR_VERSION = 0x1001;
+  
+  /** 
+   * The size required for the zero-terminated attributes list, for the current context.
+   **/
 	public static final int ALC_ATTRIBUTES_SIZE = 0x1002;
+  
+  /**
+   * Expects a destination of ALC_CURRENT_ATTRIBUTES_SIZE,
+   * and provides the attribute list for the current context of the specified device.
+   */
 	public static final int ALC_ALL_ATTRIBUTES = 0x1003;
 
+  /** The specifier string for the default device */
 	public static final int ALC_DEFAULT_DEVICE_SPECIFIER = 0x1004;
+  
+  /** The specifier string for the device */
 	public static final int ALC_DEVICE_SPECIFIER = 0x1005;
+  
+  /** The extensions string for diagnostics and printing */
 	public static final int ALC_EXTENSIONS = 0x1006;
 
+  /** Frequency for mixing output buffer, in units of Hz. */
 	public static final int ALC_FREQUENCY = 0x1007;
+  
+  /** Refresh intervalls, in units of Hz. */ 
 	public static final int ALC_REFRESH = 0x1008;
+  
+  /** Flag, indicating a synchronous context. */
 	public static final int ALC_SYNC = 0x1009;
 
 	/** The device argument does not name a valid device */
@@ -158,8 +200,16 @@ public class ALC {
 	protected static native void nDestroy();
 
   /**
-   * Returns strings related to the context.
+   * The application can obtain certain strings from ALC.
+   * 
+   * <code>ALC_DEFAULT_DEVICE_SPECIFIER</code> - The specifer string for the default device
+   * <code>ALC_DEVICE_SPECIFIER</code> - The specifer string for the device 
+   * <code>ALC_EXTENSIONS</code> - The extensions string for diagnostics and printing.
    *
+   * In addition, printable error message strings are provided for all valid error tokens,
+   * including <code>ALC_NO_ERROR</code>,<code>ALC_INVALID_DEVICE</code>, <code>ALC_INVALID_CONTEXT</code>,
+   * <code>ALC_INVALID_ENUM</code>, <code>ALC_INVALID_VALUE</code>.
+   * 
    * @param pname Property to get
    * @return String property from device
    */
@@ -170,7 +220,21 @@ public class ALC {
   native static String nGetString(int device, int pname);
 
 	/**
-	 * Returns integers related to the context.
+	 * The application can query ALC for information using an integer query function.
+   * For some tokens, <code>null</code> is a legal deviceHandle. In other cases, specifying a <code>null</code>
+   * device will generate an <code>ALC_INVALID_DEVICE</code> error. The application has to
+   * specify the size of the destination buffer provided. A <code>null</code> destination or a zero
+   * size parameter will cause ALC to ignore the query.
+   * 
+   * <code>ALC_MAJOR_VERSION</code> - Major version query.
+   * <code>ALC_MINOR_VERSION</code> - Minor version query.
+   * <code>ALC_ATTRIBUTES_SIZE</code> - The size required for the zero-terminated attributes list, 
+   * for the current context. <code>null</code> is an invalid device. <code>null</code> (no current context 
+   * for the specified device) is legal.
+   * <code>ALC_ALL_ATTRIBUTES</code> - Expects a destination of <code>ALC_CURRENT_ATTRIBUTES_SIZE</code>,
+   * and provides the attribute list for the current context of the specified device.
+   * <code>null</code> is an invalid device. <code>null</code> (no current context for the specified device)
+   * will return the default attributes defined by the specified device.
 	 *
 	 * @param pname Property to get
 	 * @param size Size of destination buffer provided
@@ -183,8 +247,13 @@ public class ALC {
   native static void nGetIntegerv(int device, int pname, int size, Buffer integerdata);    
 
 	/**
-	 * Opens the named device. If null is specied, the implementation will
-	 * provide an implementation specic default.
+	 * The <code>alcOpenDevice</code> function allows the application (i.e. the client program) to
+   * connect to a device (i.e. the server).
+   *
+   * If the function returns <code>null</code>, then no sound driver/device has been found. The
+   * argument is a null terminated string that requests a certain device or device
+   * configuration. If <code>null</code> is specified, the implementation will provide an
+   * implementation specific default.
 	 *
 	 * @param devicename name of device to open
 	 * @return opened device, or null
@@ -192,14 +261,26 @@ public class ALC {
 	native static ALCdevice alcOpenDevice(String devicename);
 
 	/**
-	 * Closes the supplied device.
+	 * The <code>alcCloseDevice</code> function allows the application (i.e. the client program) to
+   * disconnect from a device (i.e. the server).
+   * 
+   * If deviceHandle is <code>null</code> or invalid, an <code>ALC_INVALID_DEVICE</code> error will be
+   * generated. Once closed, a deviceHandle is invalid.
 	 *
 	 * @param device address of native device to close
 	 */
 	native static void alcCloseDevice(int device);
 
 	/**
-	 * Creates a context using a specified device.
+	 * A context is created using <code>alcCreateContext</code>. The device parameter has to be a valid
+   * device. The attribute list can be <code>null</code>, or a zero terminated list of integer pairs
+   * composed of valid ALC attribute tokens and requested values.
+   * 
+   * Context creation will fail if the application requests attributes that, by themselves,
+   * can not be provided. Context creation will fail if the combination of specified
+   * attributes can not be provided. Context creation will fail if a specified attribute, or
+   * the combination of attributes, does not match the default values for unspecified
+   * attributes.
 	 *
 	 * @param device address of device to associate context to
 	 * @param attrList Buffer to read attributes from
@@ -208,7 +289,15 @@ public class ALC {
 	native static ALCcontext alcCreateContext(int device, Buffer attrList);
 
 	/**
-	 * Makes the supplied context the current one
+	 * To make a Context current with respect to AL Operation (state changes by issueing
+   * commands), <code>alcMakeContextCurrent</code> is used. The context parameter can be <code>null</code>
+   * or a valid context pointer. The operation will apply to the device that the context
+   * was created for.
+   * 
+   * For each OS process (usually this means for each application), only one context can
+   * be current at any given time. All AL commands apply to the current context.
+   * Commands that affect objects shared among contexts (e.g. buffers) have side effects
+   * on other contexts.
 	 *
 	 * @param context address of context to make current
 	 * @return true if successfull, false if not
@@ -216,7 +305,15 @@ public class ALC {
 	native static boolean alcMakeContextCurrent(int context);
 
   /**
-   * Tells a context to begin processing.
+   * The current context is the only context accessible to state changes by AL commands
+   * (aside from state changes affecting shared objects). However, multiple contexts can
+   * be processed at the same time. To indicate that a context should be processed (i.e.
+   * that internal execution state like offset increments are supposed to be performed),
+   * the application has to use <code>alcProcessContext</code>.
+   *
+   * Repeated calls to <code>alcProcessContext</code> are legal, and do not affect a context that is
+   * already marked as processing. The default state of a context created by
+   * alcCreateContext is that it is not marked as processing.
    */
   public static void alcProcessContext() {
     nProcessContext(AL.context.context);
@@ -225,14 +322,15 @@ public class ALC {
   native static void nProcessContext(int context);
 
 	/**
-	 * Gets the current context
+	 * The application can query for, and obtain an handle to, the current context for the
+   * application. If there is no current context, <code>null</code> is returned.
 	 *
 	 * @return Current ALCcontext
 	 */
 	native static ALCcontext alcGetCurrentContext();
 
 	/**
-	 * Retrives the device associated with the supplied context
+	 * The application can query for, and obtain an handle to, the device of a given context.
 	 *
 	 * @param context address of context to get device for
 	 * @param ALCdevice associated with context
@@ -240,21 +338,39 @@ public class ALC {
 	native static ALCdevice alcGetContextsDevice(int context);
 
 	/**
-	 * Suspends processing on supplied context
+	 * The application can suspend any context from processing (including the current
+   * one). To indicate that a context should be suspended from processing (i.e. that
+   * internal execution state like offset increments is not supposed to be changed), the
+   * application has to use <code>alcSuspendContext</code>.
+   * 
+   * Repeated calls to <code>alcSuspendContext</code> are legal, and do not affect a context that is
+   * already marked as suspended. The default state of a context created by
+   * <code>alcCreateContext</code> is that it is marked as suspended.
 	 *
 	 * @param context address of context to suspend
 	 */
 	native static void alcSuspendContext(int context);
 
 	/**
-	 * Destroys supplied context
+	 * The correct way to destroy a context is to first release it using <code>alcMakeCurrent</code> and
+   * <code>null</code>. Applications should not attempt to destroy a current context.
 	 *
 	 * @param context address of context to Destroy
 	 */
 	native static void alcDestroyContext(int context);
 
 	/**
-	 * Retrieves the current context error state.
+	 * ALC uses the same conventions and mechanisms as AL for error handling. In
+   * particular, ALC does not use conventions derived from X11 (GLX) or Windows
+   * (WGL). The <code>alcGetError</code> function can be used to query ALC errors.
+   * 
+   * Error conditions are specific to the device.
+   * 
+   * ALC_NO_ERROR - The device handle or specifier does name an accessible driver/server.
+   * <code>ALC_INVALID_DEVICE</code> - The Context argument does not name a valid context.
+   * <code>ALC_INVALID_CONTEXT</code> - The Context argument does not name a valid context.
+   * <code>ALC_INVALID_ENUM</code> - A token used is not valid, or not applicable.
+   * <code>ALC_INVALID_VALUE</code> - An value (e.g. attribute) is not valid, or not applicable.
 	 *
 	 * @return Errorcode from ALC statemachine
 	 */
@@ -265,7 +381,10 @@ public class ALC {
 	native static int nGetError(int device);
 
 	/**
-	 * Query if a specified context extension is available.
+   * Verify that a given extension is available for the current context and the device it
+   * is associated with.
+   * A <code>null</code> name argument returns <code>ALC_FALSE</code>, as do invalid and unsupported string
+   * tokens.
 	 *
 	 * @param extName name of extension to find
 	 * @return true if extension is available, false if not
@@ -277,7 +396,11 @@ public class ALC {
 	native static boolean nIsExtensionPresent(int device, String extName);
 
 	/**
-	 * retrieves the enum value for a specified enumeration name.
+	 * Enumeration/token values are device independend, but tokens defined for
+   * extensions might not be present for a given device. But only the tokens defined
+   * by the AL core are guaranteed. Availability of extension tokens dependends on the ALC extension.
+   * 
+   * Specifying a <code>null</code> name parameter will cause an <code>ALC_INVALID_VALUE</code> error.
 	 *
 	 * @param enumName name of enum to find
 	 * @return value of enumeration

src/java/org/lwjgl/openal/ALCcontext.java

@@ -37,7 +37,7 @@ import java.nio.ByteOrder;
 
 /**
  * $Id$
- *
+ * <br>
  * Wrapper class, to make ALC contexts behave like the orginal api.
  *
  * @author Brian Matzon <brian@matzon.dk>

src/java/org/lwjgl/openal/ALCdevice.java

@@ -33,7 +33,7 @@ package org.lwjgl.openal;
 
 /**
  * $Id$
- *
+ * <br>
  * Wrapper class, to make ALC devices behave like the orginal api.
  *
  * @author Brian Matzon <brian@matzon.dk>

src/java/org/lwjgl/openal/ALConstants.java

@@ -33,7 +33,7 @@ package org.lwjgl.openal;
 
 /**
  * $Id$
- *
+ * <br>
  * This class contains all OpenAL constants, including extensions.
  *
  * @author Brian Matzon <brian@matzon.dk>

src/java/org/lwjgl/openal/BaseAL.java

@@ -39,7 +39,7 @@ import org.lwjgl.Sys;
 
 /**
  * $Id$
- *
+ * <br>
  * The base AL functionality (no actual AL methods).
  *
  * This has been provided as a base class that we can use for either the

src/java/org/lwjgl/openal/BaseALConstants.java

@@ -33,7 +33,7 @@ package org.lwjgl.openal;
 
 /**
  * $Id$
- *
+ * <br>
  * This class implements all basic OpenAL constants.
  *
  * @author Brian Matzon <brian@matzon.dk>

src/java/org/lwjgl/openal/CoreAL.java

@@ -39,7 +39,7 @@ import java.nio.DoubleBuffer;
 
 /**
  * $Id$
- *
+ * <br>
  * This is the core OpenAL class. This class implements 
  * AL.h version 1.0
  *
@@ -49,21 +49,33 @@ import java.nio.DoubleBuffer;
 public abstract class CoreAL extends BaseAL implements BaseALConstants {
 
 	/**
-	 * Enables a feature of the OpenAL driver.
+   * The application can temporarily disable certain AL capabilities on a per Context
+   * basis. This allows the driver implementation to optimize for certain subsets of
+   * operations. Enabling and disabling capabilities is handled using a function pair.
 	 *
 	 * @param capability name of a capability to enable
 	 */
 	public static native void alEnable(int capability);
 
 	/**
-	 * Disables a feature of the OpenAL driver.
+	 * The application can temporarily disable certain AL capabilities on a per Context
+   * basis. This allows the driver implementation to optimize for certain subsets of
+   * operations. Enabling and disabling capabilities is handled using a function pair.
 	 *
 	 * @param capability name of a capability to disable
 	 */
 	public static native void alDisable(int capability);
 
 	/**
-	 * Checks if a specific feature is enabled in the OpenAL driver.
+	 * The application can also query whether a given capability is currently enabled or
+   * not.
+   * <p>
+   * If the token used to specify target is not legal, an AL_INVALID_ENUM error will be
+   * generated.
+   * </p>
+   * <p>
+   * At this time, this mechanism is not used. There are no valid targets.
+   * </p>
 	 *
 	 * @param capability name of a capability to check
 	 * @return true if named feature is enabled
@@ -74,41 +86,81 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	 * Hinting for implementation
 	 * NOTE: This method is a NOP, but is provided for completeness.
 	 *
-	 * @param target FIXME
-	 * @param mode FIXME
+	 * @param target The target to hint
+	 * @param mode Mode to hint
 	 */
 	public static native void alHint(int target, int mode);
 
 	/**
-	 * Returns a boolean OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	 *
 	 * @return boolean state described by pname will be returned.
 	 */
 	public static native boolean alGetBoolean(int pname);
 
 	/**
-	  * Returns an int OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	  *
 	  * @return int state described by pname will be returned.
 	  */
 	public static native int alGetInteger(int pname);
 
 	/**
-	  * Returns a float OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	  *
 	  * @return float state described by pname will be returned.
 	  */
 	public static native float alGetFloat(int pname);
 
 	/**
-	  * Returns a double OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	  *
 	  * @return double state described by pname will be returned.
 	  */
 	public static native double alGetDouble(int pname);
 
 	/**
-	  * Returns a boolean OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	  *
 	  * @param pname state to be queried
 	  * @param data Buffer to place the booleans in
@@ -116,7 +168,15 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetBooleanv(int pname, ByteBuffer data);
 
 	/**
-	  * Returns an integer OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	  *
 	  * @param pname state to be queried
 	  * @param data Buffer to place the integers in
@@ -124,7 +184,15 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetIntegerv(int pname, IntBuffer data);
 
 	/**
-	  * Returns a floating point OpenAL state.
+   * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
 	  *
 	  * @param pname state to be queried
 	  * @param data Buffer to place the floats in
@@ -132,15 +200,27 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetFloatv(int pname, FloatBuffer data);
 
 	/**
-	  * Returns a double OpenAL state.
-	  *
-	  * @param pname state to be queried
-	  * @param data Buffer to place the floats in
-	  */
+	 * Like OpenGL, AL uses a simplified interface for querying global state. 
+   * 
+   * Legal values are e.g. AL_DOPPLER_FACTOR, AL_DOPPLER_VELOCITY,
+   * AL_DISTANCE_MODEL.
+   * <p>
+   * <code>null</code> destinations are quietly ignored. AL_INVALID_ENUM is the response to errors
+   * in specifying pName. The amount of memory required in the destination
+   * depends on the actual state requested.
+   * </p>
+	 *
+	 * @param pname state to be queried
+	 * @param data Buffer to place the floats in
+	 */
 	public static native void alGetDoublev(int pname, DoubleBuffer data);
 
 	/**
-	 * Retrieve an OpenAL string property.
+	 * The application can retrieve state information global to the current AL Context.
+   * GetString will return a pointer to a constant string. Valid values for param are
+   * VERSION, RENDERER, VENDOR, and EXTENSIONS, as well as the error codes
+   * defined by AL. The application can use GetString to retrieve a string for an error
+   * code.
 	 *
 	 * @param pname The property to be returned
 	 * @return OpenAL String property
@@ -148,14 +228,91 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native String alGetString(int pname);
 
 	/**
-	 * Retrieve the current error state and then clears the error state.
+	 * The AL detects only a subset of those conditions that could be considered errors.
+   * This is because in many cases error checking would adversely impact the
+   * performance of an error-free program.
+   * <p>
+   * Each detectable error is assigned a numeric
+   * code. When an error is detected by AL, a flag is set and the error code is recorded.
+   * Further errors, if they occur, do not affect this recorded code. When GetError is
+   * called, the code is returned and the flag is cleared, so that a further error will again
+   * record its code. If a call to GetError returns AL_NO_ERROR then there has been no
+   * detectable error since the last call to GetError (or since the AL was initialized).
+   * </p>
+   * <p>
+   * Error codes can be mapped to strings. The GetString function returns a pointer to a
+   * constant (literal) string that is identical to the identifier used for the enumeration
+   * value, as defined in the specification.
+   * </p>
+   * <p>
+   * AL_NO_ERROR - "No Error" token.<br>
+   * AL_INVALID_NAME - Invalid Name parameter.<br>
+   * AL_INVALID_ENUM - Invalid parameter.<br>
+   * AL_INVALID_VALUE - Invalid enum parameter value.<br>
+   * AL_INVALID_OPERATION - Illegal call.<br>
+   * AL_OUT_OF_MEMORY - Unable to allocate memory.<br>
+   * </p>
+   * <p>
+   * The table summarizes the AL errors. Currently, when an error flag is set, results of
+   * AL operations are undefined only if AL_OUT_OF_MEMORY has occured. In other
+   * cases, the command generating the error is ignored so that it has no effect on AL
+   * state or output buffer contents. If the error generating command returns a value, it
+   * returns zero. If the generating command modifies values through a pointer
+   * argument, no change is made to these values. These error semantics apply only to
+   * AL errors, not to system errors such as memory access errors.
+   * </p>
+   * <p>
+   * Several error generation conditions are implicit in the description of the various AL
+   * commands. First, if a command that requires an enumerated value is passed a value
+   * that is not one of those specified as allowable for that command, the error
+   * AL_INVALID_ENUM results. This is the case even if the argument is a pointer to a
+   * symbolic constant if that value is not allowable for the given command. This will
+   * occur whether the value is allowable for other functions, or an invalid integer value.
+   * </p>
+   * <p>
+   * Integer parameters that are used as names for AL objects such as Buffers and
+   * Sources are checked for validity. If an invalid name parameter is specified in an AL
+   * command, an AL_INVALID_NAME error will be generated, and the command is
+   * ignored.
+   * </p>
+   * <p>
+   * If a negative integer is provided where an argument of type sizei is specified, the
+   * error AL_INVALID_VALUE results. The same error will result from attempts to set
+   * integral and floating point values for attributes exceeding the legal range for these.
+   * The specification does not guarantee that the implementation emits
+   * AL_INVALID_VALUE if a NaN or Infinity value is passed in for a float or double
+   * argument (as the specification does not enforce possibly expensive testing of
+   * floating point values).
+   * </p>
+   * <p>
+   * Commands can be invalid. For example, certain commands might not be applicable
+   * to a given object. There are also illegal combinations of tokens and values as
+   * arguments to a command. AL responds to any such illegal command with an
+   * AL_INVALID_OPERATION error.
+   * </p>
+   * <p>
+   * If memory is exhausted as a side effect of the execution of an AL command, either
+   * on system level or by exhausting the allocated resources at AL's internal disposal,
+   * the error AL_OUT_OF_MEMORY may be generated. This can also happen independent
+   * of recent commands if AL has to request memory for an internal task and fails to
+   * allocate the required memory from the operating system.
+   * </p>
+   * <p>
+   * Otherwise errors are generated only for conditions that are explicitely described in
+   * this specification.
+   * </p>
 	 *
 	 * @return current error state
 	 */
 	public static native int alGetError();
 
 	/**
-	 * Test if a specific extension is available for the OpenAL driver.
+	 * To verify that a given extension is available for the current context and the device it
+   * is associated with, use this method.
+   * <p>
+   * A <code>null</code> name argument returns AL_FALSE, as do invalid and unsupported string
+   * tokens. A <code>null</code> deviceHandle will result in an INVALID_DEVICE error.
+   * </p> 
 	 *
 	 * @param fname String describing the desired extension
 	 * @return true if extension is available, false if not
@@ -163,7 +320,19 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native boolean alIsExtensionPresent(String fname);
 
 	/**
-	 * Returns the enumeration value of an OpenAL enum described by a string.
+   * <p>
+	 * To obtain enumeration values for extensions, the application has to use
+   * GetEnumValue of an extension token. Enumeration values are defined within the
+   * AL namespace and allocated according to specification of the core API and the
+   * extensions, thus they are context-independent.
+   * </p>
+   * <p>
+   * Returns 0 if the enumeration can not be found. The presence of an enum value does
+   * not guarantee the applicability of an extension to the current context. A non-zero
+   * return indicates merely that the implementation is aware of the existence of this
+   * extension. Implementations should not attempt to return 0 to indicate that the
+   * extensions is not supported for the current context.
+   * </p>
 	 *
 	 * @param ename String describing an OpenAL enum
 	 * @return Actual int for the described enumeration name
@@ -171,7 +340,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native int alGetEnumValue(String ename);
 
 	/**
-	 * Sets an integer property of the listener
+	 * Listener attributes are changed using the Listener group of commands.
 	 *
 	 * @param pname name of the attribute to be set
 	 * @param value value to set the attribute to
@@ -179,7 +348,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alListeneri(int pname, int value);
 
 	/**
-	 * Sets a floating point property of the listener
+	 * Listener attributes are changed using the Listener group of commands.
 	 *
 	 * @param pname name of the attribute to be set
 	 * @param value floating point value to set the attribute to
@@ -187,7 +356,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alListenerf(int pname, float value);
   
   /**
-   * Sets a floating point property of the listener
+   * Listener attributes are changed using the Listener group of commands.
    *
    * @param pname name of the attribute to be set
    * @param v1 value value 1
@@ -198,7 +367,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
   
 
 	/**
-	 * Sets a floating point vector property of the listener
+	 * Listener attributes are changed using the Listener group of commands.
 	 *
 	 * @param pname name of the attribute to be set
 	 * @param floatdata Buffer to read floats from
@@ -206,7 +375,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alListenerfv(int pname, FloatBuffer floatdata);
 
 	/**
-	 * Gets an integer property of the listener.
+   * Listener state is maintained inside the AL implementation and can be queried in
+   * full.
 	 *
 	 * @param pname name of the attribute to be retrieved
 	 * @param integerdata Buffer to write integer to
@@ -214,7 +384,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetListeneri(int pname, IntBuffer integerdata);
 
 	/**
-	 * Gets a floating point property of the listener.
+   * Listener state is maintained inside the AL implementation and can be queried in
+   * full.
 	 *
 	 * @param pname name of the attribute to be retrieved
 	 * @param floatdata Buffer to write float to
@@ -222,7 +393,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetListenerf(int pname, FloatBuffer floatdata);
 
 	/**
-	 * Retrieves a floating point vector property of the listener.
+	 * Listener state is maintained inside the AL implementation and can be queried in
+   * full.
 	 *
 	 * @param pname name of the attribute to be retrieved
 	 * @param floatdata Buffer to write floats to
@@ -230,7 +402,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetListenerfv(int pname, FloatBuffer floatdata);
 
 	/**
-	 * Generate one or more sources.
+	 * The application requests a number of Sources using GenSources.
 	 *
 	 * @param n number of sources to generate
 	 * @param sources array holding sources
@@ -238,7 +410,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGenSources(int n, IntBuffer sources);
 
 	/**
-	 * Delete one or more sources.
+	 * The application requests deletion of a number of Sources by DeleteSources.
 	 *
 	 * @param n Number of sources to delete
 	 * @param source Source array to delete from
@@ -246,7 +418,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alDeleteSources(int n, IntBuffer source);
 
 	/**
-	 * Tests if a source is valid.
+	 * The application can verify whether a source name is valid using the IsSource query.
 	 *
 	 * @param id id of source to be testes for validity
 	 * @return true if id is valid, false if not
@@ -254,7 +426,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native boolean alIsSource(int id);
 
 	/**
-	 * Set an integer property of a source.
+   * Specifies the position and other properties as taken into account during
+   * sound processing.
 	 *
 	 * @param source Source to det property on
 	 * @param pname property to set
@@ -263,7 +436,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourcei(int source, int pname, int value);
 
 	/**
-	 * Set a floating point property of a source.
+   * Specifies the position and other properties as taken into account during
+   * sound processing.
 	 *
 	 * @param source Source to det property on
 	 * @param pname property to set
@@ -272,7 +446,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourcef(int source, int pname, float value);
   
   /**
-   * Sets a source property requiring three floating point values.
+   * Specifies the position and other properties as taken into account during
+   * sound processing.
    *
    * @param source Source to set property on
    * @param pname property to set
@@ -289,7 +464,8 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
   
 
 	/**
-	 * Sets a floating point vector property of a source.
+   * Specifies the position and other properties as taken into account during
+   * sound processing.
 	 *
 	 * @param source source whichs attribute is being set
 	 * @param pname name of the attribute being set 
@@ -298,7 +474,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourcefv(int source, int pname, FloatBuffer floatdata);
 
 	/**
-	 * Retrieves an integer property of a source.
+   * Source state is maintained inside the AL implementation, and the current attributes
+   * can be queried. The performance of such queries is implementation dependent, no
+   * performance guarantees are made.
 	 *
 	 * @param source source to get property from
 	 * @param pname name of property
@@ -307,7 +485,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetSourcei(int source, int pname, IntBuffer integerdata);
 
 	/**
-	 * Retrieves a floating point property of a source.
+   * Source state is maintained inside the AL implementation, and the current attributes
+   * can be queried. The performance of such queries is implementation dependent, no
+   * performance guarantees are made.
 	 *
 	 * @param source source to get property from
 	 * @param pname name of property
@@ -316,7 +496,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetSourcef(int source, int pname, FloatBuffer floatdata);
 
 	/**
-	 * Gets a floating point vector property from a Source object.
+   * Source state is maintained inside the AL implementation, and the current attributes
+   * can be queried. The performance of such queries is implementation dependent, no
+   * performance guarantees are made.
 	 *
 	 * @param source Source to get property from
 	 * @param pname property to get
@@ -325,7 +507,14 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetSourcefv(int source, int pname, FloatBuffer floatdata);
 
 	/**
-	 * Plays a set of sources.
+   * Play() applied to an AL_INITIAL Source will promote the Source to AL_PLAYING, thus
+   * the data found in the Buffer will be fed into the processing, starting at the
+   * beginning. Play() applied to a AL_PLAYING Source will restart the Source from the
+   * beginning. It will not affect the configuration, and will leave the Source in
+   * AL_PLAYING state, but reset the sampling offset to the beginning. Play() applied to a
+   * AL_PAUSED Source will resume processing using the Source state as preserved at the
+   * Pause() operation. Play() applied to a AL_STOPPED Source will propagate it to
+   * AL_INITIAL then to AL_PLAYING immediately.
 	 *
 	 * @param n number of sources to play
 	 * @param sources array of sources to play
@@ -333,7 +522,10 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourcePlayv(int n, IntBuffer sources);
 
 	/**
-	 * Pauses a set of sources.
+   * Pause() applied to an AL_INITIAL Source is a legal NOP. Pause() applied to a
+   * AL_PLAYING Source will change its state to AL_PAUSED. The Source is exempt from
+   * processing, its current state is preserved. Pause() applied to a AL_PAUSED Source is a
+   * legal NOP. Pause() applied to a AL_STOPPED Source is a legal NOP.
 	 *
 	 * @param n number of sources to pause
 	 * @param sources array of sources to pause
@@ -341,7 +533,11 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourcePausev(int n, IntBuffer sources);
 
 	/**
-	 * Stops a set of sources.
+   * Stop() applied to an AL_INITIAL Source is a legal NOP. Stop() applied to a AL_PLAYING
+   * Source will change its state to AL_STOPPED. The Source is exempt from processing,
+   * its current state is preserved. Stop() applied to a AL_PAUSED Source will change its
+   * state to AL_STOPPED, with the same consequences as on a AL_PLAYING Source. Stop()
+   * applied to a AL_STOPPED Source is a legal NOP.
 	 *
 	 * @param n number of sources to stop
 	 * @param sources array of sources to stop
@@ -349,7 +545,13 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourceStopv(int n, IntBuffer sources);
 
 	/**
-	 * Rewinds a set of sources.
+   * Rewind() applied to an AL_INITIAL Source is a legal NOP. Rewind() applied to a
+   * AL_PLAYING Source will change its state to AL_STOPPED then AL_INITIAL. The Source is
+   * exempt from processing, its current state is preserved, with the exception of the
+   * sampling offset which is reset to the beginning. Rewind() applied to a AL_PAUSED
+   * Source will change its state to AL_INITIAL, with the same consequences as on a
+   * AL_PLAYING Source. Rewind() applied to a AL_STOPPED Source promotes the Source to
+   * AL_INITIAL, resetting the sampling offset to the beginning.
 	 *
 	 * @param n number of sources to rewind
 	 * @param sources array of sources to rewind
@@ -357,35 +559,55 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourceRewindv(int n, IntBuffer sources);
 
 	/**
-	 * Play a source.
+	 * Play() applied to an AL_INITIAL Source will promote the Source to AL_PLAYING, thus
+   * the data found in the Buffer will be fed into the processing, starting at the
+   * beginning. Play() applied to a AL_PLAYING Source will restart the Source from the
+   * beginning. It will not affect the configuration, and will leave the Source in
+   * AL_PLAYING state, but reset the sampling offset to the beginning. Play() applied to a
+   * AL_PAUSED Source will resume processing using the Source state as preserved at the
+   * Pause() operation. Play() applied to a AL_STOPPED Source will propagate it to
+   * AL_INITIAL then to AL_PLAYING immediately.
 	 *
 	 * @param source Source to play
 	 */
 	public static native void alSourcePlay(int source);
 
 	/**
-	 * Pauses a source.
+	 * Pause() applied to an AL_INITIAL Source is a legal NOP. Pause() applied to a
+   * AL_PLAYING Source will change its state to AL_PAUSED. The Source is exempt from
+   * processing, its current state is preserved. Pause() applied to a AL_PAUSED Source is a
+   * legal NOP. Pause() applied to a AL_STOPPED Source is a legal NOP.
 	 *
 	 * @param source Source to pause
 	 */
 	public static native void alSourcePause(int source);
 
 	/**
-	 * Stops a source.
+	 * Stop() applied to an AL_INITIAL Source is a legal NOP. Stop() applied to a AL_PLAYING
+   * Source will change its state to AL_STOPPED. The Source is exempt from processing,
+   * its current state is preserved. Stop() applied to a AL_PAUSED Source will change its
+   * state to AL_STOPPED, with the same consequences as on a AL_PLAYING Source. Stop()
+   * applied to a AL_STOPPED Source is a legal NOP.
 	 *
 	 * @param source Source to stop
 	 */
 	public static native void alSourceStop(int source);
 
 	/**
-	 * Rewinds a source.
+	 * Rewind() applied to an AL_INITIAL Source is a legal NOP. Rewind() applied to a
+   * AL_PLAYING Source will change its state to AL_STOPPED then AL_INITIAL. The Source is
+   * exempt from processing, its current state is preserved, with the exception of the
+   * sampling offset which is reset to the beginning. Rewind() applied to a AL_PAUSED
+   * Source will change its state to AL_INITIAL, with the same consequences as on a
+   * AL_PLAYING Source. Rewind() applied to a AL_STOPPED Source promotes the Source to
+   * AL_INITIAL, resetting the sampling offset to the beginning.
 	 *
 	 * @param source Source to rewind
 	 */
 	public static native void alSourceRewind(int source);
 
 	/**
-	 * Generate one or more buffers.
+	 * The application requests a number of Buffers using GenBuffers.
 	 *
 	 * @param n number of buffers to generate
 	 * @param buffers holding buffers
@@ -393,7 +615,18 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGenBuffers(int n, IntBuffer buffers);
 
 	/**
-	 * Delete one or more buffers.
+   * <p>
+	 * The application requests deletion of a number of Buffers by calling DeleteBuffers.
+   * </p>
+   * <p>
+   * Once deleted, Names are no longer valid for use with AL function calls. Any such
+   * use will cause an AL_INVALID_NAME error. The implementation is free to defer actual
+   * release of resources.
+   * </p>
+   * <p>
+   * IsBuffer(bname) can be used to verify deletion of a buffer. Deleting bufferName 0 is
+   * a legal NOP in both scalar and vector forms of the command. The same is true for
+   * unused buffer names, e.g. such as not allocated yet, or as released already.
 	 *
 	 * @param n Number of buffers to delete
 	 * @param buffers Buffer to delete from
@@ -401,7 +634,7 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alDeleteBuffers(int n, IntBuffer buffers);
 
 	/**
-	 * Tests if buffer is valid.
+	 * The application can verify whether a buffer Name is valid using the IsBuffer query.
 	 *
 	 * @param buffer buffer to be tested for validity
 	 * @return true if supplied buffer is valid, false if not
@@ -409,7 +642,26 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native boolean alIsBuffer(int buffer);
 
 	/**
-	 * Fill a buffer with audio data.
+   * <p>
+	 * A special case of Buffer state is the actual sound sample data stored in asociation
+   * with the Buffer. Applications can specify sample data using BufferData.
+   * </p>
+   * <p>
+   * The data specified is copied to an internal software, or if possible, hardware buffer.
+   * The implementation is free to apply decompression, conversion, resampling, and
+   * filtering as needed. The internal format of the Buffer is not exposed to the
+   * application, and not accessible. Valid formats are AL_FORMAT_MONO8,
+   * AL_FORMAT_MONO16, AL_FORMAT_STEREO8, and AL_FORMAT_STEREO16. An
+   * implementation may expose other formats, see the chapter on Extensions for
+   * information on determining if additional formats are supported.
+   * </p>
+   * <p>
+   * Applications should always check for an error condition after attempting to specify
+   * buffer data in case an implementation has to generate an AL_OUT_OF_MEMORY or
+   * conversion related AL_INVALID_VALUE error. The application is free to reuse the
+   * memory specified by the data pointer once the call to BufferData returns. The
+   * implementation has to dereference, e.g. copy, the data during BufferData execution.
+   * </p>
 	 *
 	 * @param buffer Buffer to fill
 	 * @param format format sound data is in
@@ -425,7 +677,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 		int freq);
 
 	/**
-	 * Retrieves an integer property from a buffer.
+	 * Buffer state is maintained inside the AL implementation and can be queried in full.<br>
+   * ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].<br>
+   * ALC_SIZE - Size in bytes of the buffer data.<br>
 	 *
 	 * @param buffer buffer to get property from
 	 * @param pname name of property to retrieve
@@ -434,7 +688,9 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetBufferi(int buffer, int pname, IntBuffer integerdata);
 
 	/**
-	 * Retrieves a floating point property from a buffer.
+   * Buffer state is maintained inside the AL implementation and can be queried in full.<br>
+   * ALC_FREQUENCY - specified in samples per second, i.e. units of Hertz [Hz].<br>
+   * ALC_SIZE - Size in bytes of the buffer data.<br>
 	 *
 	 * @param buffer buffer to get property from
 	 * @param pname name of property to retrieve
@@ -443,7 +699,16 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alGetBufferf(int buffer, int pname, FloatBuffer floatdata);
 
 	/**
-	 * Queues a set of buffers on a source.
+   * <p>
+	 * The application can queue up one or multiple buffer names using
+   * SourceQueueBuffers. The buffers will be queued in the sequence in which they
+   * appear in the array.
+   * </p>
+   * <p>
+   * This command is legal on a Source in any state (to allow for streaming, queueing
+   * has to be possible on a AL_PLAYING Source). Queues are read-only with exception of
+   * the unqueue operation. The Buffer Name AL_NONE (i.e. 0) can be queued.
+   * </p>
 	 *
 	 * @param source source to queue buffers onto
 	 * @param n number of buffers to be queued
@@ -452,7 +717,20 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourceQueueBuffers(int source, int n, IntBuffer buffers);
 
 	/**
-	 * Unqueues a set of buffers attached to a source.
+   * <p>
+	 * Once a queue entry for a buffer has been appended to a queue and is pending
+   * processing, it should not be changed. Removal of a given queue entry is not possible
+   * unless either the Source is AL_STOPPED (in which case then entire queue is considered
+   * processed), or if the queue entry has already been processed (AL_PLAYING or AL_PAUSED
+   * Source).
+   * </p>
+   * <p>
+   * The Unqueue command removes a number of buffers entries that have nished
+   * processing, in the order of appearance, from the queue. The operation will fail if
+   * more buffers are requested than available, leaving the destination arguments
+   * unchanged. An AL_INVALID_VALUE error will be thrown. If no error, the destination
+   * argument will have been updated accordingly.
+   * </p>
 	 *
 	 * @param source source to unqueue buffers from
 	 * @param n number of buffers to be unqueued
@@ -461,22 +739,160 @@ public abstract class CoreAL extends BaseAL implements BaseALConstants {
 	public static native void alSourceUnqueueBuffers(int source, int n, IntBuffer buffers);
 
 	/**
-	 * Selects the OpenAL distance model.
+   * <p>
+	 * Samples usually use the entire dynamic range of the chosen format/encoding,
+   * independent of their real world intensity. In other words, a jet engine and a
+   * clockwork both will have samples with full amplitude. The application will then
+   * have to adjust Source AL_GAIN accordingly to account for relative differences.
+   * </p>
+   * <p>
+   * Source AL_GAIN is then attenuated by distance. The effective attenuation of a Source
+   * depends on many factors, among which distance attenuation and source and
+   * Listener AL_GAIN are only some of the contributing factors. Even if the source and
+   * Listener AL_GAIN exceed 1.0 (amplification beyond the guaranteed dynamic range),
+   * distance and other attenuation might ultimately limit the overall AL_GAIN to a value
+   * below 1.0.
+   * </p>
+   * <p> 
+   * AL currently supports three modes of operation with respect to distance
+   * attenuation. It supports two distance-dependent attenuation models, one which is
+   * similar to the IASIG I3DL2 (and DS3D) model. The application choses one of these
+   * two models (or can chose to disable distance-dependent attenuation effects model)
+   * on a per-context basis.
+   * </p>
+   * <p>
+   * Legal arguments are AL_NONE, AL_INVERSE_DISTANCE, and
+   * AL_INVERSE_DISTANCE_CLAMPED. 
+   * <br>
+   * <br>
+   * AL_NONE bypasses all distance attenuation
+   * calculation for all Sources. The implementation is expected to optimize this
+   * situation. 
+   * <br>
+   * <br>
+   * AL_INVERSE_DISTANCE_CLAMPED is the DS3D model, with
+   * AL_REFERENCE_DISTANCE indicating both the reference distance and the distance
+   * below which gain will be clamped. 
+   * <br>
+   * <br>
+   * AL_INVERSE_DISTANCE is equivalent to the DS3D
+   * model with the exception that AL_REFERENCE_DISTANCE does not imply any
+   * clamping. 
+   * <br>
+   * <br>
+   * The AL implementation is still free to apply any range clamping as
+   * necessary. The current distance model chosen can be queried using GetIntegerv and
+   * AL_DISTANCE_MODEL.
+   * </p>
 	 *
 	 * @param value distance model to be set
 	 */
 	public static native void alDistanceModel(int value);
 
 	/**
-	 * Selects the OpenAL Doppler factor value.
+   * The Doppler Effect depends on the velocities of Source and Listener relative to the
+   * medium, and the propagation speed of sound in that medium. The application
+   * might want to emphasize or de-emphasize the Doppler Effect as physically accurate
+   * calculation might not give the desired results. The amount of frequency shift (pitch
+   * change) is proportional to the speed of listener and source along their line of sight.
+   * The application can increase or decrease that frequency shift by specifying the
+   * scaling factor AL should apply to the result of the calculation.
+   * <br>
+   * <br>
+   * The Doppler Effect as implemented by AL is described by the formula below. Effects
+   * of the medium (air, water) moving with respect to listener and source are ignored.
+   * AL_DOPPLER_VELOCITY is the propagation speed relative to which the Source
+   * velocities are interpreted.
+   * 
+   * <p>
+   * <pre>
+   *   VD: AL_DOPPLER_VELOCITY
+   *   DF: AL_DOPPLER_FACTOR
+   *   vl: Listener velocity (scalar, projected on source-listener vector)
+   *   vs: Source verlocity (scalar, projected on source-listener vector)
+   *   f: Frequency in sample
+   *   f': effective Doppler shifted frequency
+   *   
+   *   f' = DF * f * (VD-vl)/(VD+vs)
+   * 
+   *   vl<0, vs>0 : source and listener approaching each other
+   *   vl>0, vs<0 : source and listener moving away from each other
+   * </pre>
+   * </p>
+   * <p>
+   * The implementation has to clamp the projected Listener velocity vl, if abs(vl) is
+   * greater or equal VD. It similarly has to clamp the projected Source velocity vs if
+   * abs(vs) is greater or equal VD.
+   * </p>
+   * <p>
+   * There are two API calls global to the current context that provide control of the two
+   * related parameters.
+   * </p>
+   * <p>
+   * AL_DOPPLER_FACTOR is a simple scaling to exaggerate or
+   * deemphasize the Doppler (pitch) shift resulting from the calculation.
+   * </p>
+   * <p>
+   * A negative value will result in an AL_INVALID_VALUE error, the command is then
+   * ignored. The default value is 1. The current setting can be queried using GetFloatv
+   * and AL_DOPPLER_FACTOR. The implementation is free to optimize the case of
+   * AL_DOPPLER_FACTOR being set to zero, as this effectively disables the effect.
+   * </p>
 	 *
 	 * @param value Doppler scale value to set
 	 */
 	public static native void alDopplerFactor(float value);
 
 	/**
-	 * Selects the OpenAL Doppler velocity value.
-	 *
+	 * The Doppler Effect depends on the velocities of Source and Listener relative to the
+   * medium, and the propagation speed of sound in that medium. The application
+   * might want to emphasize or de-emphasize the Doppler Effect as physically accurate
+   * calculation might not give the desired results. The amount of frequency shift (pitch
+   * change) is proportional to the speed of listener and source along their line of sight.
+   * The application can increase or decrease that frequency shift by specifying the
+   * scaling factor AL should apply to the result of the calculation.
+   * <br>
+   * <br>
+   * The Doppler Effect as implemented by AL is described by the formula below. Effects
+   * of the medium (air, water) moving with respect to listener and source are ignored.
+   * AL_DOPPLER_VELOCITY is the propagation speed relative to which the Source
+   * velocities are interpreted.
+	 * 
+   * <p>
+   * <pre>
+   *   VD: AL_DOPPLER_VELOCITY
+   *   DF: AL_DOPPLER_FACTOR
+   *   vl: Listener velocity (scalar, projected on source-listener vector)
+   *   vs: Source verlocity (scalar, projected on source-listener vector)
+   *   f: Frequency in sample
+   *   f': effective Doppler shifted frequency
+   *   
+   *   f' = DF * f * (VD-vl)/(VD+vs)
+   * 
+   *   vl<0, vs>0 : source and listener approaching each other
+   *   vl>0, vs<0 : source and listener moving away from each other
+   * </pre>
+   * </p>
+   * <p>
+   * The implementation has to clamp the projected Listener velocity vl, if abs(vl) is
+   * greater or equal VD. It similarly has to clamp the projected Source velocity vs if
+   * abs(vs) is greater or equal VD.
+   * </p>
+   * <p>
+   * There are two API calls global to the current context that provide control of the two
+   * related parameters.
+   * </p>
+   * <p>
+   * AL_DOPPLER_VELOCITY allows the application to change the reference (propagation)
+   * velocity used in the Doppler Effect calculation. This permits the application to use a
+   * velocity scale appropriate to its purposes.
+   * </p>
+   * <p>
+   * A negative or zero value will result in an AL_INVALID_VALUE error, the command is
+   * then ignored. The default value is 1. The current setting can be queried using
+   * GetFloatv and AL_DOPPLER_VELOCITY.
+   * </p>
+   *
 	 * @param value Doppler velocity value to set
 	 */
 	public static native void alDopplerVelocity(float value);

src/java/org/lwjgl/openal/OpenALException.java

@@ -33,7 +33,7 @@ package org.lwjgl.openal;
 
 /**
  * $Id$
- *
+ * <br>
  * Thrown by the debug build library of the LWJGL if any OpenAL operation
  * causes an error.
  *