Rewrote/added documentation for audio

ppapi/c/ppb_audio_config.h

Index: ppapi/c/ppb_audio_config.h
===================================================================
--- ppapi/c/ppb_audio_config.h	(revision 75399)
+++ ppapi/c/ppb_audio_config.h	(working copy)
@@ -15,7 +15,10 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_AudioConfig interface for establishing an
+ * audio configuration resource within the browser. Refer to the
+ * <a href="/chrome/nativeclient/docs/audio.html">Pepper Audio API Code
+ * Walkthrough</a> for information on using this interface.
  */
 
 /**
@@ -23,6 +26,12 @@
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * This enumeration contains audio frame count constants.
+ * PP_AUDIOMINSAMPLEFRAMECOUNT is the minimum possible frame count.
+ * PP_AUDIOMAXSAMPLEFRAMECOUNT is the maximum possible frame count.
+ */
 enum {
   PP_AUDIOMINSAMPLEFRAMECOUNT = 64,
   PP_AUDIOMAXSAMPLEFRAMECOUNT = 32768
@@ -36,6 +45,13 @@
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * PP_AudioSampleRate is an enumeration of the different audio sampling rates.
+ * PP_AUDIOSAMPLERATE_44100 is the sample rate used on CDs and
+ * PP_AUDIOSAMPLERATE_48000 is the sample rate used on DVDs and Digital Audio
+ * Tapes.
+ */
 typedef enum {
   PP_AUDIOSAMPLERATE_NONE = 0,
   PP_AUDIOSAMPLERATE_44100 = 44100,
@@ -52,41 +68,51 @@
  */
 
 /**
- * Audio configuration. This base configuration interface supports only stereo
- * 16bit output. This class is not mutable, therefore it is okay to access
- * instances from different threads.
+ * The PPB_AudioConfig interface contains pointers to several functions for
+ * establishing your audio configuration within the browser. This interface
+ * only supports stereo * 16bit output. This class is not mutable, therefore
+ * it is okay to access instances from different threads.
  */
 struct PPB_AudioConfig {
   /**
-   * Create a 16 bit stereo config with the given sample rate. We guarantee
-   * that PP_AUDIOSAMPLERATE_44100 and PP_AUDIOSAMPLERATE_48000 sample rates
-   * are supported. The |sample_frame_count| should be the result of calling
-   * RecommendSampleFrameCount. If the sample frame count or bit rate aren't
-   * supported, this function will fail and return a null resource.
+   * CreateStereo16bit is a pointer to a function that creates a 16 bit audio
+   * configuration resource. The |sample_frame_count| should be the result of
+   * calling RecommendSampleFrameCount. If the sample frame count or bit rate
+   * isn't supported, this function will fail and return a null resource.
    *
    * A single sample frame on a stereo device means one value for the left
    * channel and one value for the right channel.
    *
    * Buffer layout for a stereo int16 configuration:
    * int16_t *buffer16;
-   * buffer16[0] is the first left channel sample
-   * buffer16[1] is the first right channel sample
-   * buffer16[2] is the second left channel sample
-   * buffer16[3] is the second right channel sample
+   * buffer16[0] is the first left channel sample.
+   * buffer16[1] is the first right channel sample.
+   * buffer16[2] is the second left channel sample.
+   * buffer16[3] is the second right channel sample.
    * ...
-   * buffer16[2 * (sample_frame_count - 1)] is the last left channel sample
-   * buffer16[2 * (sample_frame_count - 1) + 1] is the last right channel sample
+   * buffer16[2 * (sample_frame_count - 1)] is the last left channel sample.
+   * buffer16[2 * (sample_frame_count - 1) + 1] is the last right channel
+   * sample.
    * Data will always be in the native endian format of the platform.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] sample_rate A PP_AudioSampleRate which is either
+   * PP_AUDIOSAMPLERATE_44100 or PP_AUDIOSAMPLERATE_48000.
+   * @param[in] sample_frame_count A uint32_t frame count returned from the
+   * RecommendSampleFrameCount function.
+   * @return A PP_Resource containing the PPB_Audio_Config if successful or
+   * a null resource if the sample frame count or bit rate are not supported.
    */
   PP_Resource (*CreateStereo16Bit)(PP_Instance instance,
                                    PP_AudioSampleRate sample_rate,
                                    uint32_t sample_frame_count);
 
-  /*
-   * Returns a supported sample frame count closest to the given requested
-   * count. The sample frame count determines the overall latency of audio.
-   * Since one "frame" is always buffered in advance, smaller frame counts
-   * will yield lower latency, but higher CPU utilization.
+  /**
+   * RecommendSampleFrameCount is a pointer to a function that returns the
+   * supported sample frame count closest to the requested count. The sample
+   * frame count determines the overall latency of audio. Since one "frame" is
+   * always buffered in advance, smaller frame counts will yield lower latency,
+   * but higher CPU utilization.
    *
    * Supported sample frame counts will vary by hardware and system (consider
    * that the local system might be anywhere from a cell phone or a high-end
@@ -95,26 +121,44 @@
    * system, but values in between aren't necessarily valid. This function
    * will return a supported count closest to the requested value.
    *
+   * @param[in] sample_rate A PP_AudioSampleRate which is either
+   * PP_AUDIOSAMPLERATE_44100 or PP_AUDIOSAMPLERATE_48000.
+   * @param[in] requested_sample_frame_count A uint_32t requested frame count.
    * If you pass 0 as the requested sample count, the recommended sample for
    * the local system is returned.
+   * @return A uint32_t containing the recommended sample frame count if
+   * successful.
    */
   uint32_t (*RecommendSampleFrameCount)(PP_AudioSampleRate sample_rate,
                                         uint32_t requested_sample_frame_count);
 
   /**
-   * Returns true if the given resource is an AudioConfig object.
+   * IsAudioConfig is a pointer to a function that determines if the given
+   * resource is a PPB_Audio_Config.
+   *
+   * @param[in] resource A PP_Resource containing the audio config resource.
+   * @return A PP_BOOL containing PP_TRUE if the given resource is
+   * an AudioConfig resource, otherwise PP_FALSE.
    */
   PP_Bool (*IsAudioConfig)(PP_Resource resource);
 
   /**
-   * Returns the sample rate for the given AudioConfig resource. If the
-   * resource is invalid, this will return PP_AUDIOSAMPLERATE_NONE.
+   * GetSampleRate is a pointer to a function that returns the sample
+   * rate for the given PPB_Audio_Config.
+   *
+   * @param[in] config A PP_Resource containing the PPB_Audio_Config.
+   * @return A PP_AudioSampleRate containing sample rate or
+   * PP_AUDIOSAMPLERATE_NONE if the resource is invalid.
    */
   PP_AudioSampleRate (*GetSampleRate)(PP_Resource config);
 
   /**
-   * Returns the sample frame count for the given AudioConfig resource. If the
-   * resource is invalid, this will return 0. See RecommendSampleFrameCount for
+   * GetSampleFrameCount is a pointer to a function that returns the sample
+   * frame count for the given PPB_Audio_Config.
+   *
+   * @param[in] config A PP_Resource containing the audio config resource.
+   * @return A uint32_t containing sample frame count or
+   * 0 if the resource is invalid. See RecommendSampleFrameCount for
    * more on sample frame counts.
    */
   uint32_t (*GetSampleFrameCount)(PP_Resource config);