Index: /trunk/src/VBox/Devices/Audio/DrvHostALSAAudio.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DrvHostALSAAudio.cpp	(revision 87299)
+++ /trunk/src/VBox/Devices/Audio/DrvHostALSAAudio.cpp	(revision 87300)
@@ -76,19 +76,16 @@
 *********************************************************************************************************************************/
 
+/**
+ * Structure for maintaining an ALSA audio stream.
+ */
 typedef struct ALSAAUDIOSTREAM
 {
     /** The stream's acquired configuration. */
     PPDMAUDIOSTREAMCFG pCfg;
-    union
-    {
-        struct
-        {
-        } In;
-        struct
-        {
-        } Out;
-    };
+    /** Pointer to allocated ALSA PCM configuration to use. */
     snd_pcm_t          *phPCM;
+    /** Scratch buffer. */
     void               *pvBuf;
+    /** Size (in bytes) of allocated scratch buffer. */
     size_t              cbBuf;
 } ALSAAUDIOSTREAM, *PALSAAUDIOSTREAM;
@@ -116,4 +113,7 @@
 #define ALSA_RECOVERY_TRIES_MAX    5
 
+/**
+ * Structure for maintaining an ALSA audio stream configuration.
+ */
 typedef struct ALSAAUDIOSTREAMCFG
 {
@@ -125,4 +125,5 @@
     /** Whether resampling should be performed by alsalib or not. */
     int                 resample;
+    /** Number of audio channels. */
     int                 nchannels;
     /** Buffer size (in audio frames). */
@@ -136,5 +137,10 @@
 
 
-
+/**
+ * Converts internal audio PCM properties to an ALSA PCM format.
+ *
+ * @returns Converted ALSA PCM format.
+ * @param   pProps              Internal audio PCM configuration to convert.
+ */
 static snd_pcm_format_t alsaAudioPropsToALSA(PPDMAUDIOPCMPROPS pProps)
 {
@@ -159,4 +165,11 @@
 
 
+/**
+ * Converts an ALSA PCM format to internal PCM properties.
+ *
+ * @returns VBox status code.
+ * @param   fmt                 ALSA PCM format to convert.
+ * @param   pProps              Where to store the converted PCM properties on success.
+ */
 static int alsaALSAToAudioProps(snd_pcm_format_t fmt, PPDMAUDIOPCMPROPS pProps)
 {
@@ -244,4 +257,13 @@
 
 
+/**
+ * Sets the software parameters of an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream to set software parameters for.
+ * @param   fIn                 Whether this is an input stream or not.
+ * @param   pCfgReq             Requested configuration to set.
+ * @param   pCfgObt             Obtained configuration on success. Might differ from requested configuration.
+ */
 static int alsaStreamSetSWParams(snd_pcm_t *phPCM, bool fIn, PALSAAUDIOSTREAMCFG pCfgReq, PALSAAUDIOSTREAMCFG pCfgObt)
 {
@@ -306,4 +328,10 @@
 
 
+/**
+ * Closes an ALSA stream
+ *
+ * @returns VBox status code.
+ * @param   pphPCM              ALSA stream to close.
+ */
 static int alsaStreamClose(snd_pcm_t **pphPCM)
 {
@@ -329,4 +357,13 @@
 
 
+/**
+ * Opens (creates) an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   fIn                 Whether this is an input stream to create or not.
+ * @param   pCfgReq             Requested configuration to create stream with.
+ * @param   pCfgObt             Obtained configuration the stream got created on success.
+ * @param   pphPCM              Where to store the ALSA stream handle on success.
+ */
 static int alsaStreamOpen(bool fIn, PALSAAUDIOSTREAMCFG pCfgReq, PALSAAUDIOSTREAMCFG pCfgObt, snd_pcm_t **pphPCM)
 {
@@ -523,5 +560,11 @@
 #endif
 
-
+/**
+ * Returns the available audio frames queued.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream handle.
+ * @param   pFramesAvail        Where to store the available frames.
+ */
 static int alsaStreamGetAvail(snd_pcm_t *phPCM, snd_pcm_sframes_t *pFramesAvail)
 {
@@ -556,5 +599,10 @@
 }
 
-
+/**
+ * Tries to recover an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream handle.
+ */
 static int alsaStreamRecover(snd_pcm_t *phPCM)
 {
@@ -571,5 +619,10 @@
 }
 
-
+/**
+ * Resumes an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream to resume.
+ */
 static int alsaStreamResume(snd_pcm_t *phPCM)
 {
@@ -585,5 +638,4 @@
     return VINF_SUCCESS;
 }
-
 
 /**
@@ -608,5 +660,4 @@
     return rc;
 }
-
 
 /**
@@ -870,5 +921,10 @@
 }
 
-
+/**
+ * Destroys an ALSA input stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA input stream to destroy.
+ */
 static int alsaDestroyStreamIn(PALSAAUDIOSTREAM pStreamALSA)
 {
@@ -884,5 +940,10 @@
 }
 
-
+/**
+ * Destroys an ALSA output stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA output stream to destroy.
+ */
 static int alsaDestroyStreamOut(PALSAAUDIOSTREAM pStreamALSA)
 {
@@ -898,5 +959,12 @@
 }
 
-
+/**
+ * Creates an ALSA output stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA output stream to create.
+ * @param   pCfgReq             Requested configuration to create stream with.
+ * @param   pCfgAcq             Obtained configuration the stream got created with on success.
+ */
 static int alsaCreateStreamOut(PALSAAUDIOSTREAM pStreamALSA, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq)
 {
@@ -951,5 +1019,12 @@
 }
 
-
+/**
+ * Creates an ALSA input stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA input stream to create.
+ * @param   pCfgReq             Requested configuration to create stream with.
+ * @param   pCfgAcq             Obtained configuration the stream got created with on success.
+ */
 static int alsaCreateStreamIn(PALSAAUDIOSTREAM pStreamALSA, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq)
 {
@@ -1004,5 +1079,11 @@
 }
 
-
+/**
+ * Controls an ALSA input stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA input stream to control.
+ * @param   enmStreamCmd        Stream command to issue.
+ */
 static int alsaControlStreamIn(PALSAAUDIOSTREAM pStreamALSA, PDMAUDIOSTREAMCMD enmStreamCmd)
 {
@@ -1069,5 +1150,11 @@
 }
 
-
+/**
+ * Controls an ALSA output stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA output stream to control.
+ * @param   enmStreamCmd        Stream command to issue.
+ */
 static int alsaControlStreamOut(PALSAAUDIOSTREAM pStreamALSA, PDMAUDIOSTREAMCMD enmStreamCmd)
 {