Cleaning up and adding new docs

ppapi/c/ppb.h

Index: ppapi/c/ppb.h
===================================================================
--- ppapi/c/ppb.h	(revision 73808)
+++ ppapi/c/ppb.h	(working copy)
@@ -7,8 +7,8 @@
 
 /**
  * @file
- * Defines the API ...
- *
+ * This file defines a type for storing a pointer to an interface supported
+ * by the browser.

[dmichael(do not use this one), 2011/02/08 17:04:38]

Not sure about this wording...  maybe instead say 'This file defines a function
pointer type for the PPB_GetInterface function.'  Or something.  

[jond, 2011/02/09 16:42:04]

Done.

[jond, 2011/02/09 16:42:04]

Done.

  */
 
 /**
@@ -17,8 +17,16 @@
  */
 
 /**
- * Returns an interface pointer for the interface of the given name, or NULL
- * if the interface is not supported. Interface names should be ASCII.
+ * This value contains a pointer to an interface supported by the browser

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

This is defining a function type, not a value.  It's going to be tricky to be
both accurate and understandable.  The good news is, it should be pretty
familiar to experienced C developers.

Maybe "This function pointer type defines the signature for the PPB_GetInterface
function.  [then the paragraph that's currently 2nd describing how you get the
PPB_GetInterface function pointer that you can actually invoke].  I'd move the
2nd part of this paragraph in to its own paragraph.

[jond, 2011/02/09 16:42:04]

I think I got it. You'll have to check. On 2011/02/08 21:51:17, dmichael wrote:

+ * (given the interface name). Browser interface names should be ASCII

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

"should be ASCII" is worded for PPAPI developers who are defining new
interfaces.  If our audience is primarily users of PPAPI, we should instead say
"Browser interface names are ASCII strings..."  (note "should be" -> "are")

[jond, 2011/02/09 16:42:04]

Done.

[jond, 2011/02/09 16:42:04]

Done.

+ * and are generally defined in the header file for the interface, such
+ * as PP_AUDIO_INTERFACE found in ppb.audio.h or PPB_GRAPHICS_2D_INTERFACE in
+ * ppb_graphics_2d.h.
+ *
+ * A generic PPB_GetInterface pointer is passed to PPP_InitializedModule when
+ * your module is loaded. You can use this pointer to request a pointer to a
+ * specific browser interface.
+ * This value will be NULL if the interface is not supported on the browser.
  */
 typedef const void* (*PPB_GetInterface)(const char* interface_name);
 /**