Trivial changes to PPAPI headers

These trivial changes make the PPAPI headers more consistent.
This allows the headers to more closely match the autogenerated
ones simplifying validation before we switch over to IDL.

TEST= tryserver
BUG= http://code.google.com/p/chromium/issues/detail?id=76271
Review URL: http://codereview.chromium.org/7333003

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

11 files changed, 133 insertions, 98 deletions

diff --git a/ppapi/c/pp_completion_callback.h b/ppapi/c/pp_completion_callback.h
index bc7074a..2b1cfe7 100644
--- a/ppapi/c/pp_completion_callback.h
+++ b/ppapi/c/pp_completion_callback.h
@@ -73,6 +73,9 @@ typedef enum {
 } PP_CompletionCallback_Flag;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_CompletionCallback_Flag, 4);
 
+/**
+ * @}
+ */
 
 /**
  * @addtogroup Structs
diff --git a/ppapi/c/pp_errors.h b/ppapi/c/pp_errors.h
index 4a7b3e3..055584e 100644
--- a/ppapi/c/pp_errors.h
+++ b/ppapi/c/pp_errors.h
@@ -16,7 +16,8 @@
  * @{
  */
 
-/** This enumeration contains enumerators of all PPAPI error codes.
+/**
+ * This enumeration contains enumerators of all PPAPI error codes.
  * Errors are negative valued.
  */
 enum {
@@ -94,7 +95,8 @@ enum {
   /** This value indicates failure due to a time limit being exceeded. */
   PP_ERROR_TIMEDOUT = -30,
 
-  /** This value indicates that the user cancelled rather than providing
+  /**
+   * This value indicates that the user cancelled rather than providing
    * expected input.
    */
   PP_ERROR_USERCANCEL = -40
@@ -102,7 +104,6 @@ enum {
 
 /**
  * @}
- * End of addtogroup Enums
  */
 
 #endif  /* PPAPI_C_PP_ERRORS_H_ */
diff --git a/ppapi/c/pp_file_info.h b/ppapi/c/pp_file_info.h
index 8d82225..e433b5d 100644
--- a/ppapi/c/pp_file_info.h
+++ b/ppapi/c/pp_file_info.h
@@ -59,8 +59,8 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileSystemType, 4);
  * such as size, type, and creation time.
  */
 struct PP_FileInfo {
-  /** This value represents the size of the file. */
-  int64_t size;  /* Measured in bytes */
+  /** This value represents the size of the file measured in bytes */
+  int64_t size;
 
   /**
    * This value represents the type of file as defined by the
diff --git a/ppapi/c/pp_input_event.h b/ppapi/c/pp_input_event.h
index 4726e74..8b60783 100644
--- a/ppapi/c/pp_input_event.h
+++ b/ppapi/c/pp_input_event.h
@@ -233,6 +233,31 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Wheel, 24);
  */
 
 /**
+ * The PP_InputEventData union represents all input event data types.
+ */
+union PP_InputEventData {
+  struct PP_InputEvent_Key key;
+  struct PP_InputEvent_Character character;
+  struct PP_InputEvent_Mouse mouse;
+  struct PP_InputEvent_Wheel wheel;
+
+  /**
+   * This value allows new events to be added without changing the size of
+   * this struct.
+   */
+  char padding[64];
+};
+/**
+ * @}
+ */
+
+/**
+ *
+ * @addtogroup Structs
+ * @{
+ */
+
+/**
  * The PP_InputEvent struct represents all input events.
  */
 struct PP_InputEvent {
@@ -252,19 +277,11 @@ struct PP_InputEvent {
    */
   PP_TimeTicks time_stamp;
 
-  /** This value represents the event type and its specific data. */
-  union {
-    struct PP_InputEvent_Key key;
-    struct PP_InputEvent_Character character;
-    struct PP_InputEvent_Mouse mouse;
-    struct PP_InputEvent_Wheel wheel;
+  /**
+   * This value represents the event type and its specific data.
+   */
+  union PP_InputEventData u;
 
-    /**
-     * This value allows new events to be added without changing the size of
-     * this struct.
-     */
-    char padding[64];
-  } u;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent, 80);
 /**
diff --git a/ppapi/c/pp_var.h b/ppapi/c/pp_var.h
index ad465f0..34b364a 100644
--- a/ppapi/c/pp_var.h
+++ b/ppapi/c/pp_var.h
@@ -80,6 +80,54 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
  * @}
  */
 
+
+/**
+ * @addtogroup Structs
+ * @{
+ */
+
+/**
+ * The PP_VarValue union stores the data for any one of the types listed
+ * in the PP_VarType enum.
+ */
+union PP_VarValue {
+  /**
+   * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
+   * <code>as_bool</code> represents the value of this <code>PP_Var</code> as
+   * <code>PP_Bool</code>.
+   */
+  PP_Bool as_bool;
+
+  /**
+   * If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
+   * <code>as_int</code> represents the value of this <code>PP_Var</code> as
+   * <code>int32_t</code>.
+   */
+  int32_t as_int;
+
+  /**
+   * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
+   * <code>as_double</code> represents the value of this <code>PP_Var</code>
+   * as <code>double</code>.
+   */
+  double as_double;
+
+  /**
+   * If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
+   * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>, or
+   * <code>PP_VARTYPE_DICTIONARY</code>,
+   * <code>as_id</code> represents the value of this <code>PP_Var</code> as
+   * an opaque handle assigned by the browser. This handle is guaranteed
+   * never to be 0, so a module can initialize this ID to 0 to indicate a
+   * "NULL handle."
+   */
+  int64_t as_id;
+};
+/**
+ * @}
+ */
+
+
 /**
  * @addtogroup Structs
  * @{
@@ -115,39 +163,7 @@ struct PP_Var {
    * the fields of <code>value</code> is valid at a time based upon
    * <code>type</code>.
    */
-  union {
-    /**
-     * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
-     * <code>as_bool</code> represents the value of this <code>PP_Var</code> as
-     * <code>PP_Bool</code>.
-     */
-    PP_Bool as_bool;
-
-    /**
-     * If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
-     * <code>as_int</code> represents the value of this <code>PP_Var</code> as
-     * <code>int32_t</code>.
-     */
-    int32_t as_int;
-
-    /**
-     * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
-     * <code>as_double</code> represents the value of this <code>PP_Var</code>
-     * as <code>double</code>.
-     */
-    double as_double;
-
-    /**
-     * If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
-     * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>, or
-     * <code>PP_VARTYPE_DICTIONARY</code>,
-     * <code>as_id</code> represents the value of this <code>PP_Var</code> as
-     * an opaque handle assigned by the browser. This handle is guaranteed
-     * never to be 0, so a module can initialize this ID to 0 to indicate a
-     * "NULL handle."
-     */
-    int64_t as_id;
-  } value;
+  union PP_VarValue value;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
 /**
diff --git a/ppapi/c/ppb_audio.h b/ppapi/c/ppb_audio.h
index 39d02b5..1ee4fbf 100644
--- a/ppapi/c/ppb_audio.h
+++ b/ppapi/c/ppb_audio.h
@@ -7,7 +7,6 @@
 
 #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"
 
@@ -72,29 +71,31 @@ typedef void (*PPB_Audio_Callback)(void* sample_buffer,
  * ...audio_callback() will now be periodically invoked on a seperate thread...
  */
 struct PPB_Audio {
- /**
-  * 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
-  * 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);
+  /**
+   * 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
+   * 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);
   /**
    * IsAudio is a pointer to a function that determines if the given
    * resource is an audio resource.
@@ -145,5 +146,5 @@ struct PPB_Audio {
  * @}
  */
 
-#endif  /* PPAPI_C_PPB_DEVICE_CONTEXT_AUDIO_H_ */
+#endif  /* PPAPI_C_PPB_AUDIO_H_ */
 
diff --git a/ppapi/c/ppb_file_io.h b/ppapi/c/ppb_file_io.h
index 9e9330b..364e14d 100644
--- a/ppapi/c/ppb_file_io.h
+++ b/ppapi/c/ppb_file_io.h
@@ -67,7 +67,7 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileOpenFlags, 4);
 #define PPB_FILEIO_INTERFACE PPB_FILEIO_INTERFACE_0_5
 
 /**
- * @addtogroup Structs
+ * @addtogroup Interfaces
  * @{
  */
 /**
@@ -125,7 +125,7 @@ struct PPB_FileIO {
    *
    * @param[in] file_io A <code>PP_Resource</code> corresponding to a
    * FileIO.
-   * @param[in] info The <code>PP_FileInfo</code> structure representing all
+   * @param[out] info The <code>PP_FileInfo</code> structure representing all
    * information about the file.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion of Query().
@@ -136,19 +136,19 @@ struct PPB_FileIO {
                    struct PP_FileInfo* info,
                    struct PP_CompletionCallback callback);
 
-   /**
-    * Touch() Updates time stamps for the file opened by this FileIO object.
-    * This function will fail if the FileIO object has not been opened.
-    *
-    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
-    * FileIO.
-    * @param[in] last_access_time The last time the FileIO was accessed.
-    * @param[in] last_modified_time The last time the FileIO was modified.
-    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
-    * completion of Touch().
-    *
-    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
-    */
+  /**
+   * Touch() Updates time stamps for the file opened by this FileIO object.
+   * This function will fail if the FileIO object has not been opened.
+   *
+   * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
+   * FileIO.
+   * @param[in] last_access_time The last time the FileIO was accessed.
+   * @param[in] last_modified_time The last time the FileIO was modified.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion of Touch().
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
   int32_t (*Touch)(PP_Resource file_io,
                    PP_Time last_access_time,
                    PP_Time last_modified_time,
diff --git a/ppapi/c/ppb_input_event.h b/ppapi/c/ppb_input_event.h
index 0d33c74..ddd3ac5 100644
--- a/ppapi/c/ppb_input_event.h
+++ b/ppapi/c/ppb_input_event.h
@@ -482,4 +482,4 @@ struct PPB_KeyboardInputEvent {
   struct PP_Var (*GetCharacterText)(PP_Resource character_event);
 };
 
-#endif  // PPAPI_C_PPB_INPUT_EVENT_H_
+#endif  /* PPAPI_C_PPB_INPUT_EVENT_H_ */
diff --git a/ppapi/c/ppb_url_loader.h b/ppapi/c/ppb_url_loader.h
index 8c5d7dd..0ce27c0 100644
--- a/ppapi/c/ppb_url_loader.h
+++ b/ppapi/c/ppb_url_loader.h
@@ -6,12 +6,11 @@
 #define PPAPI_C_PPB_URL_LOADER_H_
 
 #include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_completion_callback.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 
-struct PP_CompletionCallback;
-
 #define PPB_URLLOADER_INTERFACE_0_2 "PPB_URLLoader;0.2"
 #define PPB_URLLOADER_INTERFACE PPB_URLLOADER_INTERFACE_0_2
 
diff --git a/ppapi/c/ppb_url_request_info.h b/ppapi/c/ppb_url_request_info.h
index 3bded07..820dd57 100644
--- a/ppapi/c/ppb_url_request_info.h
+++ b/ppapi/c/ppb_url_request_info.h
@@ -11,8 +11,7 @@
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/c/pp_time.h"
-
-struct PP_Var;
+#include "ppapi/c/pp_var.h"
 
 /**
  * @file
diff --git a/ppapi/c/ppb_var.h b/ppapi/c/ppb_var.h
index 6f7ce0b..d22b5ce 100644
--- a/ppapi/c/ppb_var.h
+++ b/ppapi/c/ppb_var.h
@@ -6,10 +6,8 @@
 #define PPAPI_C_PPB_VAR_H_
 
 #include "ppapi/c/pp_bool.h"
-#include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_module.h"
-#include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/c/pp_var.h"
 
@@ -75,7 +73,8 @@ struct PPB_Var {
    * string object.
    */
   struct PP_Var (*VarFromUtf8)(PP_Module module,
-                               const char* data, uint32_t len);
+                               const char* data,
+                               uint32_t len);
 
   /**
    * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This