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

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

5 files changed, 237 insertions, 107 deletions

diff --git a/ppapi/c/pp_input_event.h b/ppapi/c/pp_input_event.h
index 3180186..d7a14b9 100644
--- a/ppapi/c/pp_input_event.h
+++ b/ppapi/c/pp_input_event.h
@@ -7,7 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the API used to handle mouse and keyboard input events.
  */
 
 #include "ppapi/c/pp_bool.h"
@@ -20,6 +20,10 @@
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * This enumeration contains constants representing each mouse button.
+ */
 typedef enum {
   PP_INPUTEVENT_MOUSEBUTTON_NONE   = -1,
   PP_INPUTEVENT_MOUSEBUTTON_LEFT   = 0,
@@ -32,10 +36,13 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_MouseButton, 4);
  */
 
 /**
- *
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * This enumeration contains mouse and keyboard event constants.
+ */
 typedef enum {
   PP_INPUTEVENT_TYPE_UNDEFINED   = -1,
   PP_INPUTEVENT_TYPE_MOUSEDOWN   = 0,  // PP_InputEvent_Mouse
@@ -56,10 +63,13 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Type, 4);
  */
 
 /**
- *
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * This enumeration contains event modifier constants.
+ */
 typedef enum {
   PP_INPUTEVENT_MODIFIER_SHIFTKEY         = 1 << 0,
   PP_INPUTEVENT_MODIFIER_CONTROLKEY       = 1 << 1,
@@ -84,22 +94,23 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Modifier, 4);
  */
 
 /**
- * An event representing a key up or down event.
+ * The PP_InputEvent_Key struct represents a key up or key down event.
  *
- * Key up and down events correspond to physical keys on the keyboard. The
+ * Key up and key down events correspond to physical keys on the keyboard. The
  * actual character that the user typed (if any) will be delivered in a
  * "character" event.
  *
- * If the user kills focus on the plugin while a key is down, you may not get
- * a key up event. For example, if the plugin has focus and the user presses
- * and holds shift, the plugin will see a "shift down" message. Then if they
- * click elsewhere on the web page, the plugin focus will be lost and no more
- * input events will be delivered. If you depend on getting key up events, you
- * will also want to handle "lost focus" as the equivalent of "all keys up."
+ * If the user loses focus on the module while a key is down, a key up
+ * event might not occur. For example, if the module has focus and the user
+ * presses and holds the shift key, the module will see a "shift down" message.
+ * Then if the user clicks elsewhere on the web page, the module's focus will
+ * be lost and no more input events will be delivered.
  *
+ * If your module depends on receiving key up events, it should also handle
+ * "lost focus" as the equivalent of "all keys up."
  */
 struct PP_InputEvent_Key {
-  /** A combination of the EVENT_MODIFIER flags. */
+  /** This value is a bit field combination of the EVENT_MODIFIER flags. */
   uint32_t modifier;
 
   /**
@@ -120,7 +131,7 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
  */
 
 /**
- * An event representing a typed character.
+ * The PP_InputEvent_Character struct represents a typed character event.
  *
  * Normally, the program will receive a key down event, followed by a character
  * event, followed by a key up event. The character event will have any
@@ -128,7 +139,7 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
  * a '%'. The key down and up events will give you the scan code for the "5"
  * key, and the character event will give you the '%' character.
  *
- * You may not get a character event for all key down if the key doesn't
+ * You may not get a character event for all key down events if the key doesn't
  * generate a character. Likewise, you may actually get multiple character
  * events in a row. For example, some locales have an accent key that modifies
  * the next character typed. You might get this stream of events: accent down,
@@ -136,19 +147,18 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
  * accent character event (it was modified by the previous accent key), letter
  * key up.  If the letter can't be combined with the accent, like an umlaut and
  * an 'R', the system might send unlaut down, umlaut up, 'R' key down, umlaut
- * character ("whoops, I can't combine it with 'R', I better just send the raw
- * unlaut so it isn't lost"), 'R' character event, 'R' key up.
- *
+ * character (can't combine it with 'R', so just send the raw unlaut so it
+ * isn't lost"), 'R' character event, 'R' key up.
  */
 struct PP_InputEvent_Character {
   /** A combination of the EVENT_MODIFIER flags. */
   uint32_t modifier;
 
   /**
-   * The character the user typed, as a single null-terminated UTF-8 character.
-   * Any unused bytes will be filled with null bytes. Since the maximum UTF-8
-   * character is 4 bytes, there will always be at least one null at the end
-   * so you can treat this as a null-termianted UTF-8 string.
+   * This value represents the typed character as a single null-terminated UTF-8
+   * character. Any unused bytes will be filled with null bytes. Since the
+   * maximum UTF-8 character is 4 bytes, there will always be at least one null
+   * at the end so you can treat this as a null-termianted UTF-8 string.
    */
   char text[5];
 };
@@ -162,26 +172,40 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Character, 12);
  * @{
  */
 
-/** Represents a mouse event for everything other than the mouse wheel. */
+/**
+ * The PP_InputEvent_Mouse struct represents all mouse events except
+ * mouse wheel events.
+ */
 struct PP_InputEvent_Mouse {
-  /** A combination of the EVENT_MODIFIER flags. */
+  /** This value is a bit field combination of the EVENT_MODIFIER flags. */
   uint32_t modifier;
 
   /**
-   * Which button changed in the case of mouse down or up events. For mouse
-   * move, enter, and leave events, this will be PP_EVENT_MOUSEBUTTON_NONE.
+   * This value represents the button that changed for mouse down or up events.
+   * This value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and
+   * leave events.
    */
   PP_InputEvent_MouseButton button;
 
   /**
-   * The coordinates of the mouse when the event occurred.
+   * This values represents the x coordinate of the mouse when the event
+   * occurred.
    *
-   * In most cases these coordinates will just be integers, but they may not
-   * be in some cases. For example, the plugin element might be arbitrarily
-   * scaled or transformed in the DOM, and translating a mouse event into the
-   * coordinate space of the plugin will give non-integer values.
+   * In most, but not all, cases these coordinates will just be integers.
+   * For example, the plugin element might be arbitrarily scaled or transformed
+   * in the DOM, and translating a mouse event into the coordinate space of the
+   * plugin will give non-integer values.
    */
   float x;
+  /**
+   * This values represents the y coordinate of the mouse when the event
+   * occurred.
+   *
+   * In most, but not all, cases these coordinates will just be integers.
+   * For example, the plugin element might be arbitrarily scaled or transformed
+   * in the DOM, and translating a mouse event into the coordinate space of the
+   * plugin will give non-integer values.
+   */
   float y;
 
   /** TODO(brettw) figure out exactly what this means. */
@@ -196,8 +220,12 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Mouse, 20);
  * @addtogroup Structs
  * @{
  */
+
+/**
+ * The PP_InputEvent_Wheel struct represents all mouse wheel events.
+ */
 struct PP_InputEvent_Wheel {
-  /** A combination of the EVENT_MODIFIER flags. */
+  /** This value represents a combination of the EVENT_MODIFIER flags. */
   uint32_t modifier;
 
   /**
@@ -222,6 +250,8 @@ struct PP_InputEvent_Wheel {
    * "clicks".
    */
   float delta_x;
+
+  /** This value represents */
   float delta_y;
 
   /**
@@ -243,6 +273,8 @@ struct PP_InputEvent_Wheel {
    * of scrolling as for a mouse that has a discrete mouse wheel.
    */
   float wheel_ticks_x;
+
+  /** This value represents */
   float wheel_ticks_y;
 
   /**
@@ -261,22 +293,28 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Wheel, 24);
  * @addtogroup Structs
  * @{
  */
+
+/**
+ * The PP_InputEvent struct represents all input events.
+ */
 struct PP_InputEvent {
-  /** Identifies the type of the event. */
+  /** This value represents the type of the event. */
   PP_InputEvent_Type type;
 
-  /* Ensure the time_stamp is aligned on an 8-byte boundary relative to the
-     start of the struct. Some compilers align doubles on 8-byte boundaries
-     for 32-bit x86, and some align on 4-byte boundaries. */
+  /** This value ensure the time_stamp is aligned on an 8-byte boundary
+   * relative to the start of the struct. Some compilers align doubles
+   * on 8-byte boundaries for 32-bit x86, and some align on 4-byte boundaries.
+   */
   int32_t padding;
 
   /**
-   * When this event was generated. This is not relative to any particular
-   * epoch, the most you can do is compare time stamps.
+   * This value represents the time that this event was generated. This value
+   * is not relative to any particular epoch; the most you can do is compare
+   * time stamps.
    */
   PP_TimeTicks time_stamp;
 
-  /** Event-specific data. */
+  /** This value represents the event type and its specific data. */
   union {
     struct PP_InputEvent_Key key;
     struct PP_InputEvent_Character character;
@@ -284,8 +322,8 @@ struct PP_InputEvent {
     struct PP_InputEvent_Wheel wheel;
 
     /**
-     * Allows new events to be added without changing the size of this
-     * struct.
+     * This value allows new events to be added without changing the size of
+     * this struct.
      */
     char padding[64];
   } u;
diff --git a/ppapi/c/pp_stdint.h b/ppapi/c/pp_stdint.h
index 385fce4..ed397f5 100644
--- a/ppapi/c/pp_stdint.h
+++ b/ppapi/c/pp_stdint.h
@@ -7,8 +7,9 @@
 
 /**
  * @file
- * Provides a definition of C99 sized types
- * across different compilers.
+ * This file provides a definition of C99 sized types
+ * for Microsoft compilers. These definitions only apply
+ * for trusted modules.
  */
 
 /**
@@ -18,13 +19,28 @@
  */
 #if defined(_MSC_VER)
 
+/** This value represents a guaranteed unsigned 8 bit integer. */
 typedef unsigned char uint8_t;
+
+/** This value represents a guaranteed signed 8 bit integer. */
 typedef signed char int8_t;
+
+/** This value represents a guaranteed unsigned 16 bit short. */
 typedef unsigned short uint16_t;
+
+/** This value represents a guaranteed signed 16 bit short. */
 typedef short int16_t;
+
+/** This value represents a guaranteed unsigned 32 bit integer. */
 typedef unsigned int uint32_t;
+
+/** This value represents a guaranteed signed 32 bit integer. */
 typedef int int32_t;
+
+/** This value represents a guaranteed signed 64 bit integer. */
 typedef __int64 int64_t;
+
+/** This value represents a guaranteed unsigned 64 bit integer. */
 typedef unsigned __int64 uint64_t;
 /**
  * @}
diff --git a/ppapi/c/ppb.h b/ppapi/c/ppb.h
index f777d0e..8b06088 100644
--- a/ppapi/c/ppb.h
+++ b/ppapi/c/ppb.h
@@ -7,8 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
- *
+ * This file defines a function pointer type for the PPB_GetInterface function.
  */
 
 /**
@@ -17,8 +16,15 @@
  */
 
 /**
- * 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 function pointer type defines the signature for the PPB_GetInterface
+ * function. 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. Browser interface
+ * names are ASCII strings 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.
+ *
+ * This value will be NULL if the interface is not supported on the browser.
  */
 typedef const void* (*PPB_GetInterface)(const char* interface_name);
 /**
diff --git a/ppapi/c/ppb_instance.h b/ppapi/c/ppb_instance.h
index 852e215..2037cd9 100644
--- a/ppapi/c/ppb_instance.h
+++ b/ppapi/c/ppb_instance.h
@@ -14,21 +14,41 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_Instance interface implemented by the
+ * browser and containing pointers to functions related to
+ * the module instance on a web page.
  *
  * @addtogroup Interfaces
  * @{
  */
 
+/**
+ * The PPB_Instance interface contains pointers to functions
+ * related to the module instance on a web page.
+ *
+ */
 struct PPB_Instance {
-  /** Returns a reference to the DOM window containing this instance. */
+  /**
+   * GetWindowObject is a pointer to a function that determines
+   * the DOM window containing this module instance.
+   *
+   * @param[in] instance A PP_Instance whose WindowObject should be retrieved.
+   * @return A PP_Var containing window object on success.
+   */
   struct PP_Var (*GetWindowObject)(PP_Instance instance);
 
-  /** Returns a reference to the DOM element containing this instance. */
+  /**
+   * GetOwnerElementObject is a pointer to a function that determines
+   * the DOM element containing this module instance.
+   *
+   * @param[in] instance A PP_Instance whose WindowObject should be retrieved.
+   * @return A PP_Var containing DOM element on success.
+   */
   struct PP_Var (*GetOwnerElementObject)(PP_Instance instance);
 
   /**
-   * Binds the given graphics device as the current drawing surface. The
+   * BindGraphics is a pointer to a function that binds the given
+   * graphics as the current drawing surface. The
    * contents of this device is what will be displayed in the plugin's area
    * on the web page. The device must be a 2D or a 3D device.
    *
@@ -42,42 +62,47 @@ struct PPB_Instance {
    * to move a device between instances, first unbind it from the old one, and
    * then rebind it to the new one.
    *
-   * Returns PP_TRUE if the bind was successful. False means the device was not
-   * the correct type. On success, a reference to the device will be held by
-   * the plugin instance, so the caller can release its reference if it
-   * chooses.
-   *
    * Binding a device will invalidate that portion of the web page to flush the
    * contents of the new device to the screen.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] device A PP_Resourse representing the graphics device.
+   * @return PP_Bool containing PP_TRUE if bind was successful or PP_FALSE if
+   * the device was not the correct type. On success, a reference to the
+   * device will be held by the plugin instance, so the caller can release
+   * its reference if it chooses.
    */
   PP_Bool (*BindGraphics)(PP_Instance instance, PP_Resource device);
 
   /**
-   * Returns PP_TRUE if the instance is full-frame.  Such a plugin represents
+   * IsFullFrame is a pointer to a function that determines if the
+   * module instance is full-frame (repr). Such a module represents
    * the entire document in a frame rather than an embedded resource. This can
    * happen if the user does a top level navigation or the page specifies an
    * iframe to a resource with a MIME type registered by the plugin.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @return A PP_Bool containing PP_TRUE if the instance is full-frame.
    */
   PP_Bool (*IsFullFrame)(PP_Instance instance);
 
   /**
-   * Executes the given script in the context of the frame containing the
-   * plugin.
+   * ExecuteScript is a pointer to a function that executes the given
+   * script in the context of the frame containing the module.
    *
-   * The exception, if any, will be returned in *exception. As
-   * with the PPB_Var interface, the exception parameter,
-   * if non-NULL, must be initialized
+   * The exception, if any, will be returned in *exception. As with the PPB_Var
+   * interface, the exception parameter, if non-NULL, must be initialized
    * to a void exception or the function will immediately return. On success,
-   * the exception parameter will be set to a "void" var. On failure, the return
-   * value will be a "void" var.
+   * the exception parameter will be set to a "void" var. On failure, the
+   * return value will be a "void" var.
    *
-   * @param script A string containing the JavaScript to execute.
-   * @param exception Initialize this to NULL if you don't want exception info;
-   *     initialize this to a void exception if you do.
-   *     See the function description for details.
+   * @param[in] script A string containing the JavaScript to execute.
+   * @param[in/out] exception PP_Var containing the exception. Initialize
+   * this to NULL if you don't want exception info; initialize this to a void
+   * exception if want exception info.
    *
-   * @return The result of the script execution,
-   *     or a "void" var if execution failed.
+   * @return The result of the script execution, or a "void" var
+   * if execution failed.
    */
   struct PP_Var (*ExecuteScript)(PP_Instance instance,
                                  struct PP_Var script,
diff --git a/ppapi/c/ppp_instance.h b/ppapi/c/ppp_instance.h
index ef51f7b..8b26832 100644
--- a/ppapi/c/ppp_instance.h
+++ b/ppapi/c/ppp_instance.h
@@ -17,7 +17,8 @@ struct PP_Var;
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPP_Instance structure - a series of points to methods
+ * that you must implement in your model.
  *
  */
 
@@ -25,18 +26,42 @@ struct PP_Var;
  * @{
  */
 
+/**
+ * The PPP_Instance interface contains pointers to a series of functions that
+ * you must implement in your module. These functions can be trivial (simply
+ * return the default return value) unless you want your module
+ * to handle events such as change of focus or input events (keyboard/mouse)
+ * events.
+ */
+
 struct PPP_Instance {
   /**
-   * Called when a new plugin is instantiated on the web page. The identifier
-   * of the new instance will be passed in as the first argument (this value is
-   * generated by the browser and is an opaque handle).
+   * This value represents a pointer to a function that is called when a new
+   * module is instantiated on the web page. The identifier of the new
+   * instance will be passed in as the first argument (this value is
+   * generated by the browser and is an opaque handle). This is called for each
+   * instantiation of the NaCl module, which is each time the <embed> tag for
+   * this module is encountered.
    *
-   * It's possible for more than one plugin instance to be created within the
-   * same module (i.e. you may get more than one OnCreate without an OnDestroy
+   * It's possible for more than one module instance to be created
+   * (i.e. you may get more than one OnCreate without an OnDestroy
    * in between).
    *
-   * If the plugin reports failure from this function, the plugin will be
-   * deleted and OnDestroy will be called.
+   * If this function reports a failure (by returning @a PP_FALSE), the NaCl
+   * module will be deleted and DidDestroy will be called.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] argc The number of arguments contained in @a argn and @a argv.
+   * @param[in] argn An array of argument names.  These argument names are
+   * supplied in the <embed> tag, for example:
+   * <embed id="nacl_module" dimensions="2"> will produce two argument
+   * names: "id" and "dimensions."
+   * @param[in] argv An array of argument values.  These are the values of the
+   * arguments listed in the <embed> tag, for example
+   * <embed id="nacl_module" dimensions="2"> will produce two argument
+   * values: "nacl_module" and "2."  The indices of these values match the
+   * indices of the corresponding names in @a argn.
+   * @return @a PP_TRUE on success.
    */
   PP_Bool (*DidCreate)(PP_Instance instance,
                        uint32_t argc,
@@ -44,80 +69,97 @@ struct PPP_Instance {
                        const char* argv[]);
 
   /**
-   * Called when the plugin instance is destroyed. This will always be called,
-   * even if Create returned failure. The plugin should deallocate any data
+   * This value represents a pointer to a function that is called when the
+   * module instance is destroyed. This function will always be called,
+   * even if DidCreate returned failure. The function should deallocate any data
    * associated with the instance.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
    */
   void (*DidDestroy)(PP_Instance instance);
 
   /**
-   * Called when the position, the size, or the clip rect has changed.
-   *
-   * The |position| is the location on the page of this plugin instance. This is
-   * relative to the top left corner of the viewport, which changes as the page
-   * is scrolled.
+   * This value represents a pointer to a function that is called when the
+   * position, the size, or the clip rectangle of the element in the
+   * browser that corresponds to this NaCl module has changed.
    *
-   * The |clip| indicates the visible region of the plugin instance. This is
-   * relative to the top left of the plugin's coordinate system (not the page).
-   * If the plugin is invisible, the clip rect will be (0, 0, 0, 0).
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] position The location on the page of this NaCl module. This is
+   * relative to the top left corner of the viewport, which changes as the
+   * page is scrolled.
+   * @param[in] clip The visible region of the NaCl module. This is relative to
+   * the top left of the plugin's coordinate system (not the page).  If the
+   * plugin is invisible, @a clip will be (0, 0, 0, 0).
    */
   void (*DidChangeView)(PP_Instance instance,
                         const struct PP_Rect* position,
                         const struct PP_Rect* clip);
 
   /**
-   * Notification that the given plugin instance has gained or lost focus.
-   * Having focus means that keyboard events will be sent to your plugin
-   * instance. A plugin's default condition is that it will not have focus.
+   * This value represents a pointer to a function to handle when your module
+   * has gained or lost focus. Having focus means that keyboard events will be
+   * sent to the module. A module's default condition is that it will
+   * not have focus.
    *
-   * Note: clicks on your plugins will give focus only if you handle the
-   * click event. You signal if you handled it by returning true from
-   * HandleInputEvent. Otherwise the browser will bubble the event and give
+   * Note: clicks on modules will give focus only if you handle the
+   * click event. Return @a true from HandleInputEvent to signal that the click
+   * event was handled. Otherwise the browser will bubble the event and give
    * focus to the element on the page that actually did end up consuming it.
    * If you're not getting focus, check to make sure you're returning true from
    * the mouse click in HandleInputEvent.
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] has_focus Indicates whether this NaCl module gained or lost
+   * event focus.
    */
   void (*DidChangeFocus)(PP_Instance instance, PP_Bool has_focus);
 
   /**
-   * General handler for input events. Returns true if the event was handled or
-   * false if it was not.
+   * This value represents a pointer to a function to handle input events.
+   * Returns true if the event was handled or false if it was not.
    *
    * If the event was handled, it will not be forwarded to the web page or
    * browser. If it was not handled, it will bubble according to the normal
-   * rules. So it is important that a plugin respond accurately with whether
+   * rules. So it is important that a module respond accurately with whether
    * event propogation should continue.
    *
    * Event propogation also controls focus. If you handle an event like a mouse
-   * event, typically your plugin will be given focus. Returning false means
-   * that the click will be given to a lower part of the page and the plugin
-   * will not receive focus. This allows a plugin to be partially transparent,
+   * event, typically your module will be given focus. Returning false means
+   * that the click will be given to a lower part of the page and your module
+   * will not receive focus. This allows a module to be partially transparent,
    * where clicks on the transparent areas will behave like clicks to the
    * underlying page.
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] event The event.
+   * @return PP_TRUE if @a event was handled, PP_FALSE otherwise.
    */
   PP_Bool (*HandleInputEvent)(PP_Instance instance,
                               const struct PP_InputEvent* event);
 
   /**
-   * Called after Initialize for a full-frame plugin that was instantiated
-   * based on the MIME type of a DOMWindow navigation. This only applies to
-   * plugins that are registered to handle certain MIME types (not current
-   * Native Client plugins).
+   * This value represents a pointer to a function that is called after
+   * initialize for a full-frame plugin that was instantiated based on the MIME
+   * type of a DOMWindow navigation. This only applies to modules that are
+   * registered to handle certain MIME types (not current Native Client
+   * modules).
    *
    * The given url_loader corresponds to a PPB_URLLoader instance that is
    * already opened. Its response headers may be queried using
    * PPB_URLLoader::GetResponseInfo. The url loader is not addrefed on behalf
-   * of the plugin, if you're going to keep a reference to it, you need to
+   * of the module, if you're going to keep a reference to it, you need to
    * addref it yourself.
    *
-   * This method returns PP_FALSE if the plugin cannot handle the data. In
-   * response to this method, the plugin should call ReadResponseBody to read
+   * This method returns PP_FALSE if the module cannot handle the data. In
+   * response to this method, the module should call ReadResponseBody to read
    * the incoming data.
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] url_loader A PP_Resource an open PPB_URLLoader instance.
+   * @return PP_TRUE if the data was handled, PP_FALSE otherwise.
    */
   PP_Bool (*HandleDocumentLoad)(PP_Instance instance, PP_Resource url_loader);
 
   /**
-   * Returns a Var representing the instance object to the web page. Normally
+   * This value represents a pointer to a function that returns a Var
+   * representing the scriptable object for the given instance. Normally
    * this will be a PPP_Class object that exposes certain methods the page
    * may want to call.
    *
@@ -125,6 +167,9 @@ struct PPP_Instance {
    *
    * The returned PP_Var should have a reference added for the caller, which
    * will be responsible for Release()ing that reference.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @return A PP_Var containing scriptable object.
    */
   struct PP_Var (*GetInstanceObject)(PP_Instance instance);
 };