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

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

2 files changed, 73 insertions, 19 deletions

diff --git a/ppapi/c/pp_var.h b/ppapi/c/pp_var.h
index 2469ff9..86e7db5 100644
--- a/ppapi/c/pp_var.h
+++ b/ppapi/c/pp_var.h
@@ -11,7 +11,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the API for handling the passing of data types between
+ * your module and the page.
  */
 
 /**
@@ -19,6 +20,11 @@
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * PP_VarType is an enumeration of the different types that can be contained
+ * within a PP_VAR structure.
+ */
 typedef enum {
   PP_VARTYPE_UNDEFINED,
   PP_VARTYPE_NULL,
@@ -39,17 +45,18 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
  */
 
 /**
- * Do not rely on having a predictable and reproducible
- * int/double differentiation.
- * JavaScript has a "number" type for holding a number, and
- * does not differentiate between floating point and integer numbers. The
- * JavaScript library will try to optimize operations by using integers
- * when possible, but could end up with doubles depending on how the number
- * was arrived at.
- *
- * Your best bet is to have a wrapper for variables
- * that always gets out the type you expect, converting as necessary.
+ * The PP_VAR struct is a variant data type and can contain any
+ * value of one of the types named in the PP_VarType enum. This structure is
+ * for passing data between native code which can be strongly typed and the
+ * browser (JavaScript) which isn't strongly typed.
  *
+ * JavaScript has a "number" type for holding a number, and does not
+ * differentiate between floating point and integer numbers. The
+ * JavaScript operations will try to optimize operations by using
+ * integers when possible, but could end up with doubles. Therefore,
+ * you can't assume a numeric PP_Var will be the type you expect.
+ * Your code should be capable of handling either int32_t or double for numeric
+ * PP_Vars sent from JavaScript.
  */
 struct PP_Var {
   PP_VarType type;
@@ -82,28 +89,57 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
  * @addtogroup Functions
  * @{
  */
+
+/**
+ * PP_MakeUndefined() is a utility function used to wrap an undefined value
+ * into a PP_VAR struct for passing to the browser.
+ * @return A PP_Var structure
+ */
 PP_INLINE struct PP_Var PP_MakeUndefined() {
   struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} };
   return result;
 }
 
+/**
+ * PP_MakeNull() is a utility function used to wrap a null value into a
+ * PP_VAR struct for passing to the browser.
+ * @return A PP_Var structure
+ */
 PP_INLINE struct PP_Var PP_MakeNull() {
   struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} };
   return result;
 }
 
+/**
+ * PP_MakeBool() is a utility function used to wrap a boolean value into a
+ * PP_VAR struct for passing to the browser.
+ * @param[in] value A PP_Bool enumeration
+ * @return A PP_Var structure
+ */
 PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
   struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} };
   result.value.as_bool = value;
   return result;
 }
 
+/**
+ * PP_MakeInt32() is a utility function used to wrap a 32 bit integer value
+ * into a PP_VAR struct for passing to the browser.
+ * @param[in] value An int32
+ * @return A PP_Var structure
+ */
 PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
   struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} };
   result.value.as_int = value;
   return result;
 }
 
+/**
+ * PP_MakeDouble() is a utility function used to wrap a double value into a
+ * PP_VAR struct for passing to the browser.
+ * @param[in] value A double
+ * @return A PP_Var structure
+ */
 PP_INLINE struct PP_Var PP_MakeDouble(double value) {
   struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };
   result.value.as_double = value;
diff --git a/ppapi/c/ppp.h b/ppapi/c/ppp.h
index 173f8fa..ed1b4c3 100644
--- a/ppapi/c/ppp.h
+++ b/ppapi/c/ppp.h
@@ -17,7 +17,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines three functions that your module must
+ * implement to interact with the browser.
  *
  * {PENDING: undefine PP_EXPORT?}
  */
@@ -35,12 +36,16 @@ extern "C" {
  */
 
 /**
- * Entrypoint for the module.
+ * PPP_InitializeModule() is the entry point for a Native Client module and is
+ * called by the browser when your module loads. Your code must implement this
+ * function.
  *
- * Returns PP_OK on success, any other value on failure. Failure indicates to
- * the browser that this plugin can not be used. In this case, the plugin will
- * be unloaded and ShutdownModule will NOT be called.
+ * Failure indicates to the browser that this plugin can not be used. In this
+ * case, the plugin will be unloaded and ShutdownModule will NOT be called.
  *
+ * @param[in] module A handle to one Native Client module.
+ * @param[in] get_browser_interface An interface pointer.
+ * @return PP_OK on success. Any other value on failure.
 */
 PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
                                        PPB_GetInterface get_browser_interface);
@@ -53,7 +58,9 @@ PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
  * @{
  */
 
-/** Called before the plugin module is unloaded. */
+/** PPP_ShutdownModule() is called before the Native Client module is unloaded.
+ * Your code must implement this function.
+ */
 PP_EXPORT void PPP_ShutdownModule();
 /**
  * @}
@@ -65,8 +72,19 @@ PP_EXPORT void PPP_ShutdownModule();
  */
 
 /**
- * Returns an interface pointer for the interface of the given name, or NULL
- * if the interface is not supported. Interface names should be ASCII.
+ * PPP_GetInterface() is called by the browser to determine the PPP_Instance
+ * functions that the Native Client module implements. PPP_Instance is
+ * an interface (struct) that contains pointers to several functions your
+ * module must implement in some form (all functions can be empty, but
+ * must be implemented). If you care about things such as keyboard events
+ * or your module gaining or losing focus on a page, these functions must
+ * have code to handle those events. Refer to PPP_Instance interface for
+ * more information on these functions.
+ *
+ * @param[in] interface_name A pointer to an interface name. Interface names
+ * should be ASCII.
+ * @return An interface pointer for the interface or NULL if the interface is
+ * not supported.
  */
 PP_EXPORT const void* PPP_GetInterface(const char* interface_name);
 /**