Index: /trunk/src/VBox/Devices/Audio/DevIchAc97.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DevIchAc97.cpp	(revision 65019)
+++ /trunk/src/VBox/Devices/Audio/DevIchAc97.cpp	(revision 65020)
@@ -509,4 +509,11 @@
 }
 
+/**
+ * Retrieves the audio mixer sink of a corresponding AC'97 stream index.
+ *
+ * @returns Pointer to audio mixer sink if found, or NULL if not found / invalid.
+ * @param   pThis               AC'97 state.
+ * @param   uIndex              Stream index to get audio mixer sink for.
+ */
 DECLINLINE(PAUDMIXSINK) ichac97IndexToSink(PAC97STATE pThis, uint8_t uIndex)
 {
@@ -525,5 +532,13 @@
 }
 
-/** Fetches the buffer descriptor at _CIV. */
+/**
+ * Fetches the current BDLE (Buffer Descriptor List Entry) of an AC'97 audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ * @param   pStream             AC'97 stream to fetch BDLE for.
+ *
+ * @remark  Uses CIV as BDLE index.
+ */
 static void ichac97StreamFetchBDLE(PAC97STATE pThis, PAC97STREAM pStream)
 {
@@ -549,5 +564,9 @@
 
 /**
- * Update the BM status register
+ * Updates the status register (SR) of an AC'97 audio stream.
+ *
+ * @param   pThis               AC'97 state.
+ * @param   pStream             AC'97 stream to update SR for.
+ * @param   new_sr              New value for status register (SR).
  */
 static void ichac97StreamUpdateSR(PAC97STATE pThis, PAC97STREAM pStream, uint32_t new_sr)
@@ -620,4 +639,12 @@
 }
 
+/**
+ * Enables or disables an AC'97 audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ * @param   pStream             AC'97 stream to enable or disable.
+ * @param   fEnable             Whether to enable or disble the stream.
+ */
 static int ichac97StreamEnable(PAC97STATE pThis, PAC97STREAM pStream, bool fEnable)
 {
@@ -713,5 +740,5 @@
 
 /**
- * Creates an AC'97 stream.
+ * Creates an AC'97 audio stream.
  *
  * @returns IPRT status code.
@@ -738,5 +765,5 @@
 
 /**
- * Destroys an AC'97 stream.
+ * Destroys an AC'97 audio stream.
  *
  * @returns IPRT status code.
@@ -768,5 +795,5 @@
 
 /**
- * Creates all AC'97 streams for the device.
+ * Creates all AC'97 audio streams of the device.
  *
  * @returns IPRT status code.
@@ -822,4 +849,9 @@
 }
 
+/**
+ * Destroys all AC'97 audio streams of the device.
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97StreamsDestroy(PAC97STATE pThis)
 {
@@ -1704,4 +1736,15 @@
 }
 
+/**
+ * Sets the volume of a specific AC'97 mixer control.
+ *
+ * This currently only supports attenuation -- gain support is currently not implemented.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ * @param   index               AC'97 mixer index to set volume for.
+ * @param   enmMixerCtl         Corresponding audio mixer sink.
+ * @param   uVal                Volume value to set.
+ */
 static int ichac97MixerSetVolume(PAC97STATE pThis, int index, PDMAUDIOMIXERCTL enmMixerCtl, uint32_t uVal)
 {
@@ -1798,4 +1841,10 @@
 }
 
+/**
+ * Converts an AC'97 recording source index to a PDM audio recording source.
+ *
+ * @returns PDM audio recording source.
+ * @param   i                   AC'97 index to convert.
+ */
 static PDMAUDIORECSOURCE ichac97IndextoRecSource(uint8_t i)
 {
@@ -1816,4 +1865,10 @@
 }
 
+/**
+ * Converts a PDM audio recording source to an AC'97 recording source index.
+ *
+ * @returns AC'97 recording source index.
+ * @param   rs                  PDM audio recording source to convert.
+ */
 static uint8_t ichac97RecSourceToIndex(PDMAUDIORECSOURCE rs)
 {
@@ -1834,4 +1889,11 @@
 }
 
+/**
+ * Performs an AC'97 mixer record select to switch to a different recording
+ * source.
+ *
+ * @param   pThis               AC'97 state.
+ * @param   val                 AC'97 recording source index to set.
+ */
 static void ichac97RecordSelect(PAC97STATE pThis, uint32_t val)
 {
@@ -1845,4 +1907,10 @@
 }
 
+/**
+ * Resets the AC'97 mixer.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ */
 static int ichac97MixerReset(PAC97STATE pThis)
 {
@@ -1949,4 +2017,9 @@
 
 #ifndef VBOX_WITH_AUDIO_AC97_CALLBACKS
+/**
+ * Starts the internal audio device timer (if not started yet).
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97TimerMaybeStart(PAC97STATE pThis)
 {
@@ -1972,4 +2045,9 @@
 }
 
+/**
+ * Stops the internal audio device timer (if not stopped yet).
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97TimerMaybeStop(PAC97STATE pThis)
 {
@@ -1989,4 +2067,10 @@
 }
 
+/**
+ * Main routine to perform the actual audio data transfers from the AC'97 streams
+ * to the backend(s) and vice versa.
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97DoTransfers(PAC97STATE pThis)
 {
@@ -2030,4 +2114,11 @@
 #endif /* !VBOX_WITH_AUDIO_AC97_CALLBACKS */
 
+/**
+ * Timer callback which handles the audio data transfers on a periodic basis.
+ *
+ * @param   pDevIns             Device instance.
+ * @param   pTimer              Timer which was used when calling this.
+ * @param   pvUser              User argument as PAC97STATE.
+ */
 static DECLCALLBACK(void) ichac97Timer(PPDMDEVINS pDevIns, PTMTIMER pTimer, void *pvUser)
 {
@@ -2817,4 +2908,10 @@
 }
 
+/**
+ * Retrieves an AC'97 audio stream from an AC'97 stream index.
+ *
+ * @returns Pointer to AC'97 audio stream if found, or NULL if not found / invalid.
+ * @param                       AC'97 state.
+ */
 DECLINLINE(PAC97STREAM) ichac97GetStreamFromID(PAC97STATE pThis, uint32_t uID)
 {
@@ -2831,4 +2928,12 @@
 
 #ifdef IN_RING3
+/**
+ * Saves (serializes) an AC'97 stream using SSM.
+ *
+ * @returns IPRT status code.
+ * @param   pDevIns             Device instance.
+ * @param   pSSM                Saved state manager (SSM) handle to use.
+ * @param   pStream             AC'97 stream to save.
+ */
 static int ichac97SaveStream(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, PAC97STREAM pStream)
 {
@@ -2886,4 +2991,12 @@
 }
 
+/**
+ * Loads an AC'97 stream from SSM.
+ *
+ * @returns IPRT status code.
+ * @param   pDevIns             Device instance.
+ * @param   pSSM                Saved state manager (SSM) handle to use.
+ * @param   pStream             AC'97 stream to load.
+ */
 static int ichac97LoadStream(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, PAC97STREAM pStream)
 {