Added the Programmer's Guide for documentation

docs/guide/context-capture.md

@@ -0,0 +1,162 @@
+## Context Capture Functions
+### Functions
+* [alcCaptureOpenDevice](#alccaptureopendevice)
+* [alcCaptureCloseDevice](#alccaptureclosedevice)
+* [alcCaptureStart](#alccapturestart)
+* [alcCaptureStop](#alccapturestop)
+* [alcCaptureSamples](#alccapturesamples)
+
+#### alcCaptureOpenDevice
+##### Description
+This function opens a capture device by name.
+
+```cpp
+ALCdevice* alcCaptureOpenDevice(
+    const ALCchar* devicename,
+    ALCuint frequency,
+    ALCenum format,
+    ALCsizei buffersize
+);
+```
+
+##### Parameters
+* devicename - A pointer to a device name string
+* frequency - The frequency that the data should be captured at
+* format - The requested capture buffer format
+* buffersize - The size of the capture buffer
+
+##### Possible Error States
+| State             | Description |
+| ----------------- | ----------- |
+| ALC_INVALID_VALUE | One of the parameters has an invalid value. |
+| ALC_OUT_OF_MEMORY | The specified device is invalid, or can not capture audio. |
+
+##### Version Requirements
+OpenAL 1.1 or higher
+
+##### Remarks
+Returns the capture device pointer, or `NULL` on failure.
+
+##### See Also
+[alcCaptureCloseDevice](#alcCaptureCloseDevice)
+
+#### alcCaptureCloseDevice
+##### Description
+This function closes the specified capture device.
+
+```cpp
+ALCboolean alcCaptureCloseDevice(
+    ALCdevice* device
+);
+```
+
+##### Parameters
+* device - A pointer to a capture device
+
+##### Possible Error States
+| State              | Description |
+| ------------------ | ----------- |
+| ALC_INVALID_DEVICE | The specified device is not a valid capture device. |
+
+##### Version Requirements
+OpenAL 1.1 or higher
+
+##### Remarks
+Returns `ALC_TRUE` if the close operation was successful, `ALC_FALSE` on
+failure.
+
+##### See Also
+[alcCaptureOpenDevice](#alccaptureopendevice)
+
+#### alcCaptureStart
+##### Description
+This function begins a capture operation.
+
+```cpp
+void alcCaptureStart(
+    ALCdevice *device
+);
+```
+
+##### Parameters
+* device - A pointer to a capture device
+
+##### Possible Error States
+| State              | Description |
+| ------------------ | ----------- |
+| ALC_INVALID_DEVICE | The specified device is not a valid capture device. |
+
+##### Version Requirements
+OpenAL 1.1 or higher
+
+##### Remarks
+[alcCaptureStart](#alccapturestart) will begin recording to an internal ring
+buffer of the size specified when opening the capture device.  The application
+can then retrieve the number of samples currently available using the
+`ALC_CAPTURE_SAMPLES` token with
+[alcGetIntegerv](context-state.md#alcgetintegerv). When the application
+determines that enough samples are available for processing, then it can obtain
+them with a call to [alcCaptureSamples](#alccapturesamples).
+
+##### See Also
+[alcCaptureStop](#alccapturestop), [alcCaptureSamples](#alccapturesamples)
+
+#### alcCaptureStop
+##### Description
+This function stops a capture operation.
+
+```cpp
+void alcCaptureStop(
+    ALCdevice *device
+);
+```
+
+##### Parameters
+* device - A pointer to a capture device
+
+##### Possible Error States
+| State              | Description |
+| ------------------ | ----------- |
+| ALC_INVALID_DEVICE | The specified device is not a valid capture device. |
+
+##### Version Requirements
+OpenAL 1.1 or higher
+
+##### Remarks
+None
+
+##### See Also
+[alcCaptureStart](#alccapturestart), [alcCaptureSamples](#alccapturesamples)
+
+#### alcCaptureSamples
+##### Description
+This function completes a capture operation, and does not block.
+
+```cpp
+void alcCaptureSamples(
+    ALCdevice* device,
+    ALCvoid* buffer,
+    ALCsizei samples
+);
+```
+
+##### Parameters
+* device - A pointer to a capture device
+* buffer - A pointer to a data buffer, which must be large enough to accommodate
+           samples number of samples
+* samples - The number of samples to be retrieved
+
+##### Possible Error States
+| State              | Description |
+| ------------------ | ----------- |
+| ALC_INVALID_VALUE  | The specified number of samples is larger than the number of available samples. |
+| ALC_INVALID_DEVICE | The specified device is not a valid capture device. |
+
+##### Version Requirements
+OpenAL 1.1 or higher
+
+##### Remarks
+None
+
+##### See Also
+[alcCaptureStart](#alccapturestart), [alcCaptureStop](#alccapturestop)

docs/guide/context-device.md

@@ -0,0 +1,57 @@
+## Context Device Functions
+### Functions
+* [alcOpenDevice](#alcopendevice)
+* [alcCloseDevice](#alcclosedevice)
+
+#### alcOpenDevice
+##### Description
+This function opens a device by name.
+
+```cpp
+ALCdevice* alcOpenDevice(
+    const ALCchar* devicename
+);
+```
+
+##### Parameters
+* devicename - A null-terminated string describing a device
+
+##### Possible Error States
+The return value will be `NULL` if there is an error.
+
+##### Version Requirements
+OpenAL 1.0 or higher
+
+##### Remarks
+Returns a pointer to the opened device.  Will return `NULL` if a device can not be opened.
+
+##### See Also
+[alcCloseDevice](#alcclosedevice)
+
+#### alcCloseDevice
+##### Description
+This function closes an opened device.
+
+```cpp
+ALCboolean alcCloseDevice(
+    ALCdevice* device
+);
+```
+
+##### Parameters
+* device - A pointer to an opened device
+
+##### Possible Error States
+| State              | Description |
+| ------------------ | ----------- |
+| ALC_INVALID_DEVICE | The specified device name doesn't exist. |
+
+##### Version Requirements
+OpenAL 1.0 or higher
+
+##### Remarks
+`ALC_TRUE` will be returned on success or `ALC_FALSE` on failure.  Closing a
+device will fail if the device contains any contexts or buffers.
+
+##### See Also
+[alcOpenDevice](#alcopendevice)

docs/guide/context-error.md

@@ -0,0 +1,33 @@
+## Context Error Functions
+### Error Codes
+| Error Code          | Description |
+| ------------------- | ----------- |
+| ALC_NO_ERROR        | There is not currently an error |
+| ALC_INVALID_DEVICE  | A bad device was passed to an OpenAL function |
+| ALC_INVALID_CONTEXT | A bad context was passed to an OpenAL function |
+| ALC_INVALID_ENUM    | An unknown enum value was passed to an OpenAL function |
+| ALC_INVALID_VALUE   | An invalid value was passed to an OpenAL function |
+| ALC_OUT_OF_MEMORY   | The requested operation resulted in OpenAL running out of memory |
+
+### Functions
+* [alcGetError](#alcgeterror)
+
+#### alcGetError
+##### Description
+This function retrieves the current context error state.
+
+```cpp
+ALCenum alcGetError(ALCdevice *device);
+```
+
+##### Parameters
+* device - A pointer to the device to retrieve the error state from
+
+##### Possible Error States
+None
+
+##### Version Requirements
+OpenAL 1.0 or higher
+
+##### Remarks
+None

docs/guide/context-extension.md

@@ -0,0 +1,96 @@
+## Context Extension Functions
+### Functions
+* [alcIsExtensionPresent](#alcisextensionpresent)
+* [alcGetProcAddress](#alcgetprocaddress)
+* [alcGetEnumValue](#alcgetenumvalue)
+
+#### alcIsExtensionPresent
+##### Description
+This function queries if a specified context extension is available.
+
+```cpp
+ALCboolean alcIsExtensionPresent(
+    ALCdevice *device,
+    const ALCchar *extName
+);
+```
+
+##### Parameters
+* device - A pointer to the device to be queried for an extension
+* extName - A null-terminated string describing the extension
+
+##### Possible Error States
+| State             | Description |
+| ----------------- | ----------- |
+| ALC_INVALID_VALUE | The string pointer is not valid. |
+
+##### Version Requirements
+OpenAL 1.0 or higher
+
+##### Remarks
+Returns `ALC_TRUE` if the extension is available, `ALC_FALSE` if the extension
+is not available.
+
+##### See Also
+[alcGetProcAddress](#alcgetprocaddress), [alcGetEnumValue](#alcgetenumvalue)
+
+#### alcGetProcAddress
+##### Description
+This function retrieves the address of a specified context extension function.
+
+```cpp
+void* alcGetProcAddress(
+    ALCdevice* device,
+    const ALCchar* funcName
+);
+```
+
+##### Parameters
+* device - A pointer to the device to be queried for the function
+* funcName - a null-terminated string describing the function
+
+##### Possible Error States
+| State             | Description |
+| ----------------- | ----------- |
+| ALC_INVALID_VALUE | The string pointer is not valid. |
+
+##### Version Requirements
+OpenAL 1.0 or higher
+
+##### Remarks
+Returns the address of the function, or `NULL` if it is not found.
+
+##### See Also
+[alcIsExtensionPresent](#alcisextensionpresent),
+[alcGetEnumValue](#alcgetenumvalue)
+
+#### alcGetEnumValue
+##### Description
+This function retrieves the enum value for a specified enumeration name.
+
+```cpp
+ALCenum alcGetEnumValue(
+    ALCdevice* device,
+    const ALCchar* enumName
+);
+```
+
+##### Parameters
+* device - A pointer to the device to be queried
+* enumName - A null terminated string describing the enum value
+
+##### Possible Error States
+| State             | Description |
+| ----------------- | ----------- |
+| ALC_INVALID_VALUE | The string pointer is not valid. |
+
+##### Version Requirements
+OpenAL 1.0 or higher
+
+##### Remarks
+Returns the enum value described by the enumName string.  This is most often
+used for querying an enum value for an ALC extension.
+
+##### See Also
+[alcIsExtensionPresent](#alcisextensionpresent),
+[alcGetProcAddress](#alcgetprocaddress)