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

[dmichael(do not use this one), 2011/02/11 22:31:07]

this is a type, not a value.  Maybe:
"PPB_Audio_Callback defines the type of an audio callback function used to fill
the audio buffer with data."

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

I still think this should be reworded...

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

Done.

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

Done.

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

I don't see it here...  can you reupload?

+ * 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

[dmichael(do not use this one), 2011/02/11 22:31:07]

callback should probably be lower-case.
2 spaces after the period.

[jond, 2011/02/15 17:02:25]

Done.

+ * interface. User of audio must set the callback that will be called each time

[dmichael(do not use this one), 2011/02/11 22:31:07]

nit: 2-spaces after period
'User' should be 'Users', or even better 'Developers using the PPB_Audio API'

[jond, 2011/02/15 17:02:25]

There arn't actually two spaces after the periods.

On 2011/02/11 22:31:07, dmichael wrote:

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

Exactly ;-).  There should be.

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

Done.

+ * that the buffer needs to be filled. Refer to

[David Springer, 2011/02/11 22:12:33]

"Refer to..."  ?  It seems like there is a link missing here?

[jond, 2011/02/15 17:02:25]

Done.

[jond, 2011/02/15 17:02:25]

Done.

+ *
+ * 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.

[David Springer, 2011/02/11 22:12:33]

Just asking - we don't use @a Create for the fcn pointers?  I notice that
dropping the @a is consistent everywhere, I'm just wondering.

[jond, 2011/02/15 17:02:25]

Not sure what you are asking...

On 2011/02/11 22:12:33, David Springer wrote:

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

For doxygen, we decided to use @a for names from the code (such as parameter
names, function names, variable names, and type names).  Dave was pointing out
that you could have done that for the function pointer type names like 'Create'
in this case, but you did not.  For instance, this could say '@a Create is a
pointer...'.  If it's omitted on purpose due to a docs team decision, then
that's fine.  But I would have expected us to use @a for these function pointer
type names, so that the resulting doxygen documentation will make them stand
out.

+  * 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

[dmichael(do not use this one), 2011/02/11 22:31:07]

2 spaces after period

[jond, 2011/02/15 17:02:25]

Done.

[jond, 2011/02/15 17:02:25]

Done.

+  * call PPB_Audio functions.  The callback will be called on a different
+  * thread than the one which created the interface. For performance-critical

[dmichael(do not use this one), 2011/02/11 22:31:07]

2 spaces after period

[jond, 2011/02/15 17:02:25]

Done.

+  * applications (i.e. low-latency audio), the callback should avoid blocking
+  * or calling functions that can obtain locks, such as malloc. The layout and

[dmichael(do not use this one), 2011/02/11 22:31:07]

2 spaces after period

[jond, 2011/02/15 17:02:25]

So far only one of these (the one on line 69) had two spaces.

On 2011/02/11 22:31:07, dmichael wrote:

+  * 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 be a no-op) if called while playback is already

[dmichael(do not use this one), 2011/02/11 22:31:07]

s/and be/and is

[jond, 2011/02/15 17:02:25]

Done.

[jond, 2011/02/15 17:02:25]

Done.

+   * stopped. If a callback is in progress, StopPlayback will block until

[dmichael(do not use this one), 2011/02/11 22:31:07]

2 spaces after period

[jond, 2011/02/15 17:02:25]

Nope.

On 2011/02/11 22:31:07, dmichael wrote:

+   * callback completes.

[dmichael(do not use this one), 2011/02/11 22:31:07]

'the' callback

[jond, 2011/02/15 17:02:25]

Done.

+   */
   PP_Bool (*StopPlayback)(PP_Resource audio);
 };
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPB_DEVICE_CONTEXT_AUDIO_H_ */