Review URL: http://codereview.chromium.org/6502007

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@76256 0039d316-1c4b-4281-b951-d872f2087c98

2 files changed, 150 insertions, 65 deletions

diff --git a/ppapi/c/ppb_audio.h b/ppapi/c/ppb_audio.h
index fe0ab1a..53f58ea 100644
--- a/ppapi/c/ppb_audio.h
+++ b/ppapi/c/ppb_audio.h
@@ -15,14 +15,21 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_Audio interface for handling audio resources on
+ * the browser. Refer to the
+ * <a href="/chrome/nativeclient/docs/audio.html">Pepper Audio API Code
+ * Walkthrough</a> for information on using this interface.
  */
 
 /**
  * @addtogroup Typedefs
  * @{
  */
-// Callback function type for SetCallback.
+
+/**
+ * PPB_Audio_Callback defines the type of an audio callback function used to
+ * fill the audio buffer with data.
+ */
 typedef void (*PPB_Audio_Callback)(void* sample_buffer,
                                    size_t buffer_size_in_bytes,
                                    void* user_data);
@@ -31,57 +38,91 @@ typedef void (*PPB_Audio_Callback)(void* sample_buffer,
  */
 
 /**
- * @addtogroup Structs
+ * @addtogroup Interfaces
  * @{
  */
-// Callback-based audio interface. User of audio must set the callback that will
-// be called each time that the buffer needs to be filled.
-//
-// A C++ example:
-//
-// void audio_callback(void* sample_buffer,
-//                     size_t buffer_size_in_bytes,
-//                     void* user_data) {
-//   ... fill in the buffer with samples ...
-// }
-//
-// uint32_t obtained;
-// AudioConfig config(PP_AUDIOSAMPLERATE_44100, 4096, &obtained);
-// Audio audio(config, audio_callback, NULL);
-// audio.StartPlayback();
-//
+/**
+ * The PPB_Audio interface contains pointers to several functions for handling
+ * audio resources on the browser. This interface is a callback-based audio
+ * interface. Users of audio must set the callback that will be called each time
+ * that the buffer needs to be filled.
+ *
+ * A C++ example:
+ *
+ * void audio_callback(void* sample_buffer,
+ *                     size_t buffer_size_in_bytes,
+ *                      void* user_data) {
+ *   ... fill in the buffer with samples ...
+ *  }
+ *
+ * uint32_t obtained;
+ * AudioConfig config(PP_AUDIOSAMPLERATE_44100, 4096, &obtained);
+ * Audio audio(config, audio_callback, NULL);
+ * audio.StartPlayback();
+ */
 struct PPB_Audio {
-  // Creates a paused audio interface. No sound will be heard until
-  // StartPlayback() is called. The callback is called with the buffer address
-  // and given user data whenever the buffer needs to be filled. From within the
-  // callback, you should not call PPB_Audio functions.  The callback will be
-  // called on a different thread than the one which created the interface. For
-  // performance-critical applications (i.e. low-latency audio), the callback
-  // should avoid blocking or calling functions that can obtain locks, such as
-  // malloc. The layout and the size of the buffer passed to the audio callback
-  // will be determined by the device configuration and is specified in the
-  // AudioConfig documentation. If the configuration cannot be honored, or the
-  // callback is null, the function returns 0.
+ /**
+  * Create is a pointer to a function that creates an audio resource.
+  * No sound will be heard until StartPlayback() is called. The callback
+  * is called with the buffer address and given user data whenever the
+  * buffer needs to be filled. From within the callback, you should not
+  * call PPB_Audio functions. The callback will be called on a different
+  * thread than the one which created the interface. For performance-critical
+  * applications (i.e. low-latency audio), the callback should avoid blocking
+  * or calling functions that can obtain locks, such as malloc. The layout and
+  * the size of the buffer passed to the audio callback will be determined by
+  * the device configuration and is specified in the AudioConfig documentation.
+  *
+  * @param[in] instance A PP_Instance indentifying one instance of a module.
+  * @param[in] config A PP_Resource containing the audio config resource.
+  * @param[in] audio_callback A PPB_Audio_Callback callback function that the
+  * browser calls when it needs more samples to play.
+  * @param[in] user_data A pointer to user data used in the callback function.
+  * @return A PP_Resource containing the audio resource if successful or
+  * 0 if the configuration cannot be honored or the callback is null.
+  */
   PP_Resource (*Create)(PP_Instance instance, PP_Resource config,
                         PPB_Audio_Callback audio_callback, void* user_data);
-
   /**
-   * Returns PP_TRUE if the given resource is an Audio resource, PP_FALSE
-   * otherwise.
+   * IsAudio is a pointer to a function that determines if the given
+   * resource is an audio resource.
+   *
+   * @param[in] resource A PP_Resource containing a resource.
+   * @return A PP_BOOL containing containing PP_TRUE if the given resource is
+   * an Audio resource, otherwise PP_FALSE.
    */
   PP_Bool (*IsAudio)(PP_Resource resource);
 
-  // Get the current configuration.
+  /**
+   * GetCurrrentConfig is a pointer to a function that returns an audio config
+   * resource for the given audio resource.
+   *
+   * @param[in] config A PP_Resource containing the audio resource.
+   * @return A PP_Resource containing the audio config resource if successful.
+   */
   PP_Resource (*GetCurrentConfig)(PP_Resource audio);
 
-  // Start the playback. Begin periodically calling the callback. If called
-  // while playback is already in progress, will return PP_TRUE and be a no-op.
-  // On error, return PP_FALSE.
+  /**
+   * StartPlayback is a pointer to a function that starts the playback of
+   * the audio resource and begins periodically calling the callback.
+   *
+   * @param[in] config A PP_Resource containing the audio resource.
+   * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
+   * Also returns PP_TRUE (and be a no-op) if called while playback is already
+   * in progress.
+   */
   PP_Bool (*StartPlayback)(PP_Resource audio);
 
-  // Stop the playback. If playback is already stopped, this is a no-op and
-  // returns PP_TRUE. On error, returns PP_FALSE. If a callback is in progress,
-  // StopPlayback will block until callback completes.
+  /**
+   * StopPlayback is a pointer to a function that stops the playback of
+   * the audio resource.
+   *
+   * @param[in] config A PP_Resource containing the audio resource.
+   * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
+   * Also returns PP_TRUE (and is a no-op) if called while playback is already
+   * stopped. If a callback is in progress, StopPlayback will block until the
+   * callback completes.
+   */
   PP_Bool (*StopPlayback)(PP_Resource audio);
 };
 /**
diff --git a/ppapi/c/ppb_audio_config.h b/ppapi/c/ppb_audio_config.h
index 2ee00bd..7fee815 100644
--- a/ppapi/c/ppb_audio_config.h
+++ b/ppapi/c/ppb_audio_config.h
@@ -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 @@ enum {
  * @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 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_AudioSampleRate, 4);
  */
 
 /**
- * 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 @@ struct PPB_AudioConfig {
    * 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);