1 files changed, 83 insertions, 38 deletions

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);
 };