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 74653)
+++ ppapi/c/ppb_audio_config.h	(working copy)
@@ -15,7 +15,10 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_Audio config interface for establishing an
+ * audio configuration resource within the browser. Refer to the

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

2 spaces after the period

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

Nope.

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

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

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

I liked this extra bit of info in the web document about Audio, but I don't know
if it should be here.  May just be confusing...  'what if I'm not using a CD or
DVD?!?'.  Maybe instead explain what the sample rate is, but don't describe each
value?

I could go either way, it just strikes me as a little odd here.

 typedef enum {
   PP_AUDIOSAMPLERATE_NONE = 0,
   PP_AUDIOSAMPLERATE_44100 = 44100,
@@ -52,17 +68,17 @@
  */
 
 /**
- * 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

[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:

+ * only supports  stereo * 16bit output. This class is not mutable, therefore

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

one space after supports

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

Done.

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

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

2 spaces after period.

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

s/|sample_frame_count|/@a sample_frame_count
(right?)

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

Nope. It dawned on me you might be asking for me to put in 2 spaces after the
peroid, but one space is our standard. Two spaces is sort of dated. On
2011/02/11 22:31:07, dmichael wrote:

+   * calling RecommendSampleFrameCount. If the sample frame count or bit rate

[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:

+   * aren't supported, this function will fail and return a null resource.

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

s/aren't/isn't

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

Done.

    *
    * A single sample frame on a stereo device means one value for the left
    * channel and one value for the right channel.
@@ -75,18 +91,28 @@
    * 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) + 1] is the last right channel
+   * sample

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

These should probably all end in a period.

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

Done.

    * 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 uint_32t frame count returned from the

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

s/uint_32t/uint32_t

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

Done.

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

Done.

+   * RecommendSampleFrameCount function.
+   * @return A PP_Resource containing the audio config resource 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

[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:

+   * frame count determines the overall latency of audio. Since one "frame" is

[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:

+   * always buffered in advance, smaller frame counts will yield lower latency,

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

I think the comma after latency is superfluous.

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

Done.

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

Done.

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

[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:

    * 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.
+   * IsAudioConfit is a pointer to a function that determines if the given

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

IsAudioConfit -> IsAudioConfig (ends in 'g').

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

Done.

+   * resource is an audio config resource.
+   *
+   * @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 audio config resource.
+   *
+   * @param[in] config A PP_Resource containing the audio config resource.
+   * @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
+   * fame count for the given audio config resource.

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

s/fame/frame
Maybe instead of 'audio config' resource it should specifically say
'PPB_Audio_Config' (here and elsewhere)

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

Done.

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

Done.

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

[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:

    * more on sample frame counts.
    */
   uint32_t (*GetSampleFrameCount)(PP_Resource config);