Move standard ALC function's annotations to the header

1 files changed, 52 insertions, 19 deletions

diff --git a/include/AL/alc.h b/include/AL/alc.h
index 5786bad2..f1b6709a 100644
--- a/include/AL/alc.h
+++ b/include/AL/alc.h
@@ -22,7 +22,7 @@ extern "C" {
 #endif
 
 
-/** Deprecated macro. */
+/* Deprecated macros. */
 #define ALCAPI                                   ALC_API
 #define ALCAPIENTRY                              ALC_APIENTRY
 #define ALC_INVALID                              0
@@ -89,7 +89,7 @@ typedef void ALCvoid;
 /** Context attribute: <int> Hz. */
 #define ALC_REFRESH                              0x1008
 
-/** Context attribute: AL_TRUE or AL_FALSE. */
+/** Context attribute: AL_TRUE or AL_FALSE synchronous context? */
 #define ALC_SYNC                                 0x1009
 
 /** Context attribute: <int> requested Mono (3D) Sources. */
@@ -117,12 +117,14 @@ typedef void ALCvoid;
 #define ALC_OUT_OF_MEMORY                        0xA005
 
 
-/** Runtime ALC version. */
+/** Runtime ALC major version. */
 #define ALC_MAJOR_VERSION                        0x1000
+/** Runtime ALC minor version. */
 #define ALC_MINOR_VERSION                        0x1001
 
-/** Context attribute list properties. */
+/** Context attribute list size. */
 #define ALC_ATTRIBUTES_SIZE                      0x1002
+/** Context attribute list properties. */
 #define ALC_ALL_ATTRIBUTES                       0x1003
 
 /** String for the default device specifier. */
@@ -166,49 +168,80 @@ typedef void ALCvoid;
 #define ALC_ALL_DEVICES_SPECIFIER                0x1013
 
 
-/** Context management. */
-ALC_API ALCcontext* ALC_APIENTRY alcCreateContext(ALCdevice *device, const ALCint* attrlist);
+/* Context management. */
+
+/** Create and attach a context to the given device. */
+ALC_API ALCcontext* ALC_APIENTRY alcCreateContext(ALCdevice *device, const ALCint *attrlist);
+/**
+ * Makes the given context the active process-wide context. Passing NULL clears
+ * the active context.
+ */
 ALC_API ALCboolean  ALC_APIENTRY alcMakeContextCurrent(ALCcontext *context);
+/** Resumes processing updates for the given context. */
 ALC_API void        ALC_APIENTRY alcProcessContext(ALCcontext *context);
+/** Suspends updates for the given context. */
 ALC_API void        ALC_APIENTRY alcSuspendContext(ALCcontext *context);
+/** Remove a context from its device and destroys it. */
 ALC_API void        ALC_APIENTRY alcDestroyContext(ALCcontext *context);
+/** Returns the currently active context. */
 ALC_API ALCcontext* ALC_APIENTRY alcGetCurrentContext(void);
+/** Returns the device that a particular context is attached to. */
 ALC_API ALCdevice*  ALC_APIENTRY alcGetContextsDevice(ALCcontext *context);
 
-/** Device management. */
+/* Device management. */
+
+/** Opens the named playback device. */
 ALC_API ALCdevice* ALC_APIENTRY alcOpenDevice(const ALCchar *devicename);
+/** Closes the given playback device. */
 ALC_API ALCboolean ALC_APIENTRY alcCloseDevice(ALCdevice *device);
 
+/* Error support. */
 
-/**
- * Error support.
- *
- * Obtain the most recent Device error.
- */
+/** Obtain the most recent Device error. */
 ALC_API ALCenum ALC_APIENTRY alcGetError(ALCdevice *device);
 
+/* Extension support. */
+
 /**
- * Extension support.
- *
- * Query for the presence of an extension, and obtain any appropriate
- * function pointers and enum values.
+ * Query for the presence of an extension on the device. Pass a NULL device to
+ * query a device-inspecific extension.
  */
 ALC_API ALCboolean ALC_APIENTRY alcIsExtensionPresent(ALCdevice *device, const ALCchar *extname);
+/**
+ * Retrieve the address of a function. Given a non-NULL device, the returned
+ * function may be device-specific.
+ */
 ALC_API void*      ALC_APIENTRY alcGetProcAddress(ALCdevice *device, const ALCchar *funcname);
+/**
+ * Retrieve the value of an enum. Given a non-NULL device, the returned value
+ * may be device-specific.
+ */
 ALC_API ALCenum    ALC_APIENTRY alcGetEnumValue(ALCdevice *device, const ALCchar *enumname);
 
-/** Query function. */
+/* Query functions. */
+
+/** Returns information about the device, and error strings. */
 ALC_API const ALCchar* ALC_APIENTRY alcGetString(ALCdevice *device, ALCenum param);
+/** Returns information about the device and the version of OpenAL. */
 ALC_API void           ALC_APIENTRY alcGetIntegerv(ALCdevice *device, ALCenum param, ALCsizei size, ALCint *values);
 
-/** Capture function. */
+/* Capture functions. */
+
+/**
+ * Opens the named capture device with the given frequency, format, and buffer
+ * size.
+ */
 ALC_API ALCdevice* ALC_APIENTRY alcCaptureOpenDevice(const ALCchar *devicename, ALCuint frequency, ALCenum format, ALCsizei buffersize);
+/** Closes the given capture device. */
 ALC_API ALCboolean ALC_APIENTRY alcCaptureCloseDevice(ALCdevice *device);
+/** Starts capturing samples into the device buffer.  */
 ALC_API void       ALC_APIENTRY alcCaptureStart(ALCdevice *device);
+/** Stops capturing samples. Samples in the device buffer remain available. */
 ALC_API void       ALC_APIENTRY alcCaptureStop(ALCdevice *device);
+/** Reads samples from the device buffer. */
 ALC_API void       ALC_APIENTRY alcCaptureSamples(ALCdevice *device, ALCvoid *buffer, ALCsizei samples);
 
-/** Pointer-to-function type, useful for dynamically getting ALC entry points. */
+/* Pointer-to-function type, useful for dynamically getting ALC entry points. */
 typedef ALCcontext*    (ALC_APIENTRY *LPALCCREATECONTEXT)(ALCdevice *device, const ALCint *attrlist);
 typedef ALCboolean     (ALC_APIENTRY *LPALCMAKECONTEXTCURRENT)(ALCcontext *context);
 typedef void           (ALC_APIENTRY *LPALCPROCESSCONTEXT)(ALCcontext *context);