Cleaning up and adding new docs

ppapi/c/ppp_instance.h

 /* Copyright (c) 2010 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 #ifndef PPAPI_C_PPP_INSTANCE_H_
 #define PPAPI_C_PPP_INSTANCE_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_rect.h"
 #include "ppapi/c/pp_resource.h"
 
 struct PP_InputEvent;
 struct PP_Var;
 
 #define PPP_INSTANCE_INTERFACE "PPP_Instance;0.4"
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPP_Instance structure - a series of points to methods
+ * that you must implement in your model.
  *
  */
 
 /** @addtogroup Interfaces
  * @{
  */
 
+/**
+ * The PPP_Instance struct contains pointers to a series of methods that you
+ * must implement in your module. These methods do not have to have bodies
+ * unless you want your model to handel events such as a change of focus or

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

s/model/module
s/handel/handle
I also don't think the last sentence is true.  The methods need to have bodies,
but the bodies can be trivial (0 lines or 1 line to return a default return).

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

Done.

+ * 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">

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

s/embed/<embed

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

Done.

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

Done.

+   * will produce two arguments, one named "id" and one named "dimensions".
+   * @param[in] argv An array of argument values.  These are the values of the

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

"These are the values of the arguments listed in the <embed> tag."
Redundant...  delete?

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

Done.

+   * arguments listed in the <embed> tag.  In the previous example, there will

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

'the previous'->'this'

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

Done.

+   * be two elements in this array, "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,
                        const char* argn[],
                        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.
+   * 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 |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.
-   *
-   * 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.
    *
    * On Failure, the returned var should be a "void" var.
    *
    * 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);
 };
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPP_INSTANCE_H_ */