Rewrote/added documentation for audio

ppapi/c/ppb_audio.h

 /* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 #ifndef PPAPI_C_PPB_AUDIO_H_
 #define PPAPI_C_PPB_AUDIO_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_module.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 
 #define PPB_AUDIO_INTERFACE "PPB_Audio;0.5"
 
 /**
  * @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.
+
+/**
+ * This value contains a pointer to 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);
 /**
  * @}
  */
 
 /**
- * @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

[dmichael(do not use this one), 2011/02/15 17:41:45]

Oops, this was one of the few places that had 2 spaces :-p

[jond, 2011/02/17 21:40:45]

Done.

[jond, 2011/02/17 21:40:45]

Done.

+  * 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);
 };
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPB_DEVICE_CONTEXT_AUDIO_H_ */