Improve documentation of PPP_Instance and PPP_ShutdownModule. In particular, this adds discussion of the fast shutdown mode where the cleanup functions won't get called.

I also copied the instance documentation to the C++ class since apparently we want the C++ layer to be documented in isolation.

BUG=69909
TEST=none (no code change)
Review URL: http://codereview.chromium.org/7163003

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

3 files changed, 311 insertions, 147 deletions

diff --git a/ppapi/c/ppp.h b/ppapi/c/ppp.h
index d901dc5..3d0af05 100644
--- a/ppapi/c/ppp.h
+++ b/ppapi/c/ppp.h
@@ -37,15 +37,19 @@ extern "C" {
  */
 
 /**
- * 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.
+ * PPP_InitializeModule() is the entry point for a module and is called by the
+ * browser when your module loads. Your code must implement this function.
  *
  * 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.
+ * @param[in] module A handle to your module. Generally you should store this
+ * value since it will be required for other API calls.
+ *
+ * @param[in] get_browser_interface A pointer to the function that you can
+ * use to query for browser interfaces. Generally you should store this value
+ * for future use.
+ *
  * @return PP_OK on success. Any other value on failure.
 */
 PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
@@ -59,7 +63,18 @@ PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
  * @{
  */
 
-/** PPP_ShutdownModule() is called before the Native Client module is unloaded.
+/**
+ * PPP_ShutdownModule() is <strong>sometimes</strong> called before the module
+ * is unloaded. It is not recommended that you implement this function.
+ *
+ * There is no practical use of this function for third party plugins. Its
+ * existence is because of some internal use cases inside Chrome.
+ *
+ * Since your plugin runs in a separate process, there's no need to free
+ * allocated memory. There is also no need to free any resources since all of
+ * resources associated with an instance will be force-freed when that instance
+ * is deleted. Moreover, this function will not be called when Chrome does
+ * "fast shutdown" of a web page.
  */
 PP_EXPORT void PPP_ShutdownModule();
 /**
@@ -72,19 +87,17 @@ PP_EXPORT void PPP_ShutdownModule();
  */
 
 /**
- * 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.
+ * PPP_GetInterface() is called by the browser to query the module for
+ * interfaces it supports.
+ *
+ * Your module must implement the PPP_Instance interface or it will be
+ * unloaded. Other interfaces are optional.
+ *
+ * @param[in] interface_name A pointer to a "PPP" (plugin) interface name.
+ * Interface names are null-terminated ASCII strings.
  *
- * @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.
+ * @return A pointer for the interface or NULL if the interface is not
+ * supported.
  */
 PP_EXPORT const void* PPP_GetInterface(const char* interface_name);
 /**
diff --git a/ppapi/c/ppp_instance.h b/ppapi/c/ppp_instance.h
index 26f9614..af09beb 100644
--- a/ppapi/c/ppp_instance.h
+++ b/ppapi/c/ppp_instance.h
@@ -46,32 +46,40 @@ struct PPP_Instance {
 struct PPP_Instance_0_5 {
 #endif
   /**
-   * 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.
+   * Creation handler that is called when a new instance is created. It is
+   * called for each instantiation on the page, corresponding to one <embed>
+   * tag on the page.
    *
-   * 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).
+   * Generally you would handle this call by initializing the information
+   * your module associates with an instance and creating a mapping from the
+   * given PP_Instance handle to this data. The PP_Instance handle will be used
+   * in subsequent calls to identify which instance the call pertains to.
    *
-   * If this function reports a failure (by returning @a PP_FALSE), the NaCl
-   * module will be deleted and DidDestroy will be called.
+   * It's possible for more than one instance to be created in a single module.
+   * This means that you may get more than one OnCreate without an OnDestroy
+   * in between, and should be prepared to maintain multiple states associated
+   * with each instance.
+   *
+   * If this function reports a failure (by returning @a PP_FALSE), the
+   * instance will be deleted.
+   *
+   * @param[in] instance A new PP_Instance indentifying one instance of a
+   * module. This is an opaque handle.
    *
-   * @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
+   * 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.
+   *
+   * @return @a PP_TRUE on success or @a PP_FALSE on failure.
    */
   PP_Bool (*DidCreate)(PP_Instance instance,
                        uint32_t argc,
@@ -79,57 +87,92 @@ struct PPP_Instance_0_5 {
                        const char* argv[]);
 
   /**
-   * 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.
+   * A pointer to a instance destruction handler. This is called in many cases
+   * (see below) when a plugin instance is destroyed. It will be called even if
+   * DidCreate returned failure.
    *
-   * The instance identifier will still be valid so the plugin can perform
-   * cleanup-related tasks. Once this function is called, the PP_Instance will
-   * be invalid.
+   * Generally you will handle this call by deallocating the tracking
+   * information and the PP_Instance mapping you created in the DidCreate call.
+   * You can also free resources associated with this instance but this isn't
+   * required; all resources associated with the deleted instance will be
+   * automatically freed when this function returns.
+   *
+   * The instance identifier will still be valid during this call so the plugin
+   * can perform cleanup-related tasks. Once this function returns, the
+   * PP_Instance handle will be invalid. This means that you can't do any
+   * asynchronous operations like network requests or file writes from this
+   * function since they will be immediately canceled.
+   *
+   * <strong>Important note:</strong> This function may be skipped in certain
+   * circumstances when Chrome does "fast shutdown". Fast shutdown will happen
+   * in some cases when all plugin instances are being deleted, and no cleanup
+   * functions will be called. The module will just be unloaded and the process
+   * terminated.
    *
    * @param[in] instance A PP_Instance indentifying one instance of a module.
    */
   void (*DidDestroy)(PP_Instance instance);
 
   /**
-   * 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.
+   * 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
+   * instance has changed.
    *
-   * @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
+   * A typical implementation will check the size of the @a position argument
+   * and reallocate the graphics context when a different size is received.
+   * Note that this function will be called for scroll events where the size
+   * doesn't change, so you should always check that the size is actually
+   * different before doing any reallocations.
+   *
+   * @param[in] instance A PP_Instance indentifying the instance that has
+   * changed.
+   *
+   * @param[in] position The location on the page of the instance. 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
+   * page is scrolled. Generally the size of this value will be used to create
+   * a graphics device, and the position is ignored (most things are relative
+   * to the instance so the absolute position isn't useful in most cases).
+   *
+   * @param[in] clip The visible region of the instance. 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).
+   *
+   * It's recommended to check for invisible instances and to stop
+   * generating graphics updates in this case to save system resources. It's
+   * not usually worthwhile, however, to generate partial updates according to
+   * the clip when the instance is partially visible. Instead, update the entire
+   * region. The time saved doing partial paints is usually not significant and
+   * it can create artifacts when scrolling (this notification is sent
+   * asynchronously from scolling so there can be flashes of old content in the
+   * exposed regions).
    */
   void (*DidChangeView)(PP_Instance instance,
                         const struct PP_Rect* position,
                         const struct PP_Rect* clip);
 
   /**
-   * 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
+   * A pointer to a function that is called when an instance has gained or
+   * lost focus. Having focus means that keyboard events will be
+   * sent to the instance. An instance's default condition is that it will
    * not have focus.
    *
-   * Note: clicks on modules will give focus only if you handle the
+   * Note: clicks on instances 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.
+   *
+   * @param[in] instance A PP_Instance indentifying the instance receiving the
+   * input event.
+   *
+   * @param[in] has_focus Indicates the new focused state of the instance.
    */
   void (*DidChangeFocus)(PP_Instance instance, PP_Bool has_focus);
 
   /**
-   * 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.
+   * A pointer to a function to handle input events.  Returns PP_TRUE if the
+   * event was handled or PP_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
@@ -137,24 +180,28 @@ struct PPP_Instance_0_5 {
    * event propagation should continue.
    *
    * Event propagation also controls focus. If you handle an event like a mouse
-   * event, typically your module will be given focus. Returning false means
+   * event, typically the instance 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.
+   * will not receive focus. This allows an instance 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.
+   *
+   * @param[in] event The input event.
+   *
    * @return PP_TRUE if @a event was handled, PP_FALSE otherwise.
    */
   PP_Bool (*HandleInputEvent)(PP_Instance instance,
                               const struct PP_InputEvent* event);
 
   /**
-   * 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).
+   * 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 pre-registered to handle
+   * certain MIME types. If you haven't specifically registered to handle a
+   * MIME type or aren't positive this applies to you, your implementation of
+   * this function can just return PP_FALSE.
    *
    * The given url_loader corresponds to a PPB_URLLoader instance that is
    * already opened. Its response headers may be queried using
@@ -165,8 +212,12 @@ struct PPP_Instance_0_5 {
    * 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] instance A PP_Instance indentifying the instance that should
+   * do the load.
+   *
    * @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);
diff --git a/ppapi/cpp/instance.h b/ppapi/cpp/instance.h
index 5d0844db..e8cb5f3 100644
--- a/ppapi/cpp/instance.h
+++ b/ppapi/cpp/instance.h
@@ -5,13 +5,11 @@
 #ifndef PPAPI_CPP_INSTANCE_H_
 #define PPAPI_CPP_INSTANCE_H_
 
-/**
- * @file
- * Defines the API ...
- *
- * @addtogroup CPP
- * @{
- */
+/// @file
+/// Defines the C++ wrapper for a plugin instance.
+///
+/// @addtogroup CPP
+/// @{
 
 #include <map>
 #include <string>
@@ -22,7 +20,7 @@
 
 struct PP_InputEvent;
 
-/** The C++ interface to the Pepper API. */
+/// The C++ interface to the Pepper API.
 namespace pp {
 
 class Graphics2D;
@@ -38,120 +36,223 @@ class Widget_Dev;
 
 class Instance {
  public:
+  /// Construction of an instance should only be done in response to a browser
+  /// request in Module::CreateInstance. Otherwise, the instance will lack the
+  /// proper bookkeeping in the browser and in the C++ wrapper.
+  ///
+  /// Init() will be called immediately after the constructor. This allows you
+  /// to perform initialization tasks that can fail and to report that failure
+  /// to the browser.
   explicit Instance(PP_Instance instance);
+
+  /// When the instance is removed from the web page, the pp::Instance object
+  /// will be deleted. You should never delete the Instance object yourself
+  /// since the lifetime is handled by the C++ wrapper and is controlled by the
+  /// browser's calls to the PPP_Instance interface.
+  ///
+  /// The PP_Instance identifier will still be valid during this call so the
+  /// plugin can perform cleanup-related tasks. Once this function returns, the
+  /// PP_Instance handle will be invalid. This means that you can't do any
+  /// asynchronous operations like network requests or file writes from this
+  /// destructor since they will be immediately canceled.
+  ///
+  /// <strong>Important note:</strong> This function may be skipped in certain
+  /// circumstances when Chrome does "fast shutdown". Fast shutdown will happen
+  /// in some cases when all plugin instances are being deleted, and no cleanup
+  /// functions will be called. The module will just be unloaded and the process
+  /// terminated.
   virtual ~Instance();
 
+  /// Returns the PP_Instance identifying this object. When using the PPAPI C++
+  /// wrappers this is not normally necessary, but is required when using the
+  /// lower-level C APIs.
   PP_Instance pp_instance() const { return pp_instance_; }
 
-  /**
-   * Initializes this plugin with the given arguments.
-   * @param argc The argument count
-   * @param argn The argument names
-   * @param argv The argument values
-   * @return True on success. Returning false causes the plugin
-   * instance to be deleted and no other functions to be called.
-   */
+  /// Initializes this plugin with the given arguments. This will be called
+  /// immediately after the instance object is constructed.
+  ///
+  /// @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 True on success. Returning false causes the plugin
+  /// instance to be deleted and no other functions to be called.
   virtual bool Init(uint32_t argc, const char* argn[], const char* argv[]);
 
-
-  // @{
-  /** @name PPP_Instance methods for the plugin to override: */
-
-  /** See PPP_Instance.DidChangeView. */
+  /// @{
+  /// @name PPP_Instance methods for the plugin to override:
+
+  /// Notification that the position, the size, or the clip rectangle of the
+  /// element in the browser that corresponds to this instance has changed.
+  ///
+  /// A typical implementation will check the size of the @a position argument
+  /// and reallocate the graphics context when a different size is received.
+  /// Note that this function will be called for scroll events where the size
+  /// doesn't change, so you should always check that the size is actually
+  /// different before doing any reallocations.
+  ///
+  /// @param[in] position The location on the page of the instance. This is
+  /// relative to the top left corner of the viewport, which changes as the
+  /// page is scrolled. Generally the size of this value will be used to create
+  /// a graphics device, and the position is ignored (most things are relative
+  /// to the instance so the absolute position isn't useful in most cases).
+  ///
+  /// @param[in] clip The visible region of the instance. 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).
+  ///
+  /// It's recommended to check for invisible instances and to stop
+  /// generating graphics updates in this case to save system resources. It's
+  /// not usually worthwhile, however, to generate partial updates according to
+  /// the clip when the instance is partially visible. Instead, update the
+  /// entire region. The time saved doing partial paints is usually not
+  /// significant and it can create artifacts when scrolling (this notification
+  /// is sent asynchronously from scolling so there can be flashes of old
+  /// content in the exposed regions).
   virtual void DidChangeView(const Rect& position, const Rect& clip);
 
-  /** See PPP_Instance.DidChangeFocus. */
+  /// Notification that the instance has gained or lost focus. Having focus
+  /// means that keyboard events will be sent to the instance. An instance's
+  /// default condition is that it will not have focus.
+  ///
+  /// Note: clicks on instances 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] has_focus Indicates the new focused state of the instance.
   virtual void DidChangeFocus(bool has_focus);
 
-  /** See PPP_Instance.HandleInputEvent. */
+  /// Handles input events. Returns true if the event was handled or false if
+  /// it was not. The default implementation does nothing and returns false.
+  ///
+  /// 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 module respond accurately with whether
+  /// event propagation should continue.
+  ///
+  /// Event propagation also controls focus. If you handle an event like a mouse
+  /// event, typically the instance 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 an instance to be partially
+  /// transparent, where clicks on the transparent areas will behave like clicks
+  /// to the underlying page.
+  ///
+  /// @param[in] event The input event.
+  ///
+  /// @return true if @a event was handled, false otherwise.
   virtual bool HandleInputEvent(const PP_InputEvent& event);
 
-  /** See PPP_Instance.HandleDocumentLoad. */
+  /// Notification of a data stream available after an instance was created
+  /// based on the MIME type of a DOMWindow navigation. This only applies to
+  /// modules that are pre-registered to handle certain MIME types. If you
+  /// haven't specifically registered to handle a MIME type or aren't positive
+  /// this applies to you, you can ignore this function. The default
+  /// implementation just returns false.
+  ///
+  /// The given url_loader corresponds to a URLLoader object that is
+  /// already opened. Its response headers may be queried using GetResponseInfo.
+  /// If you want to use the URLLoader to read data, you will need to save a
+  /// copy of it or the underlying resource will be freed when this function
+  /// returns and the load will be canceled.
+  ///
+  /// This method returns 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] url_loader A PP_Resource an open PPB_URLLoader instance.
+  ///
+  /// @return true if the data was handled, false otherwise.
   virtual bool HandleDocumentLoad(const URLLoader& url_loader);
 
-  /** See PPP_Instance.GetSelectedText. */
+  // TODO(brettw) this should probably be removed.
   virtual Var GetSelectedText(bool html);
-  // @}
+  /// @}
 
-  // @{
-  /** @name PPB_Instance methods for querying the browser: */
+  /// @{
+  /// @name PPB_Instance methods for querying the browser:
 
 #ifndef PPAPI_INSTANCE_REMOVE_SCRIPTING
-  /** See PPP_Instance.GetInstanceObject. */
+  /// See PPP_Instance.GetInstanceObject.
   virtual Var GetInstanceObject();
 
-  /** See PPB_Instance.GetWindowObject. */
+  /// See PPB_Instance.GetWindowObject.
   Var GetWindowObject();
 
-  /** See PPB_Instance.GetOwnerElementObject. */
+  /// See PPB_Instance.GetOwnerElementObject.
   Var GetOwnerElementObject();
 
-  /** See PPB_Instance.ExecuteScript. */
+  /// See PPB_Instance.ExecuteScript.
   Var ExecuteScript(const Var& script, Var* exception = NULL);
 #endif
 
-  /** See PPB_Instance.BindGraphics. */
+  /// See PPB_Instance.BindGraphics.
   bool BindGraphics(const Graphics2D& graphics);
 
-  /** See PPB_Instance.BindGraphics. */
+  /// See PPB_Instance.BindGraphics.
   bool BindGraphics(const Surface3D_Dev& graphics);
 
-  /** See PPB_Instance.IsFullFrame. */
+  /// See PPB_Instance.IsFullFrame.
   bool IsFullFrame();
 
   // These functions use the PPP_Messaging and PPB_Messaging interfaces, so that
   // messaging can be done conveniently for a pp::Instance without using a
   // separate C++ class.
 
-  /** See PPP_Messaging.HandleMessage. */
+  /// See PPP_Messaging.HandleMessage.
   virtual void HandleMessage(const Var& message);
-  /** See PPB_Messaging.PostMessage. */
+  /// See PPB_Messaging.PostMessage.
   void PostMessage(const Var& message);
 
-  // @}
-
-  /**
-   * Associates a plugin instance with an interface,
-   * creating an object... {PENDING: clarify!}
-   *
-   * Many optional interfaces are associated with a plugin instance. For
-   * example, the find in PPP_Find interface receives updates on a per-instance
-   * basis. This "per-instance" tracking allows such objects to associate
-   * themselves with an instance as "the" handler for that interface name.
-   *
-   * In the case of the find example, the find object registers with its
-   * associated instance in its constructor and unregisters in its destructor.
-   * Then whenever it gets updates with a PP_Instance parameter, it can
-   * map back to the find object corresponding to that given PP_Instance by
-   * calling GetPerInstanceObject.
-   *
-   * This lookup is done on a per-interface-name basis. This means you can
-   * only have one object of a given interface name associated with an
-   * instance.
-   *
-   * If you are adding a handler for an additional interface, be sure to
-   * register with the module (AddPluginInterface) for your interface name to
-   * get the C calls in the first place.
-   *
-   * @see RemovePerInstanceObject
-   * @see GetPerInstanceObject
-   */
+  /// @}
+
+  /// Associates a plugin instance with an interface,
+  /// creating an object... {PENDING: clarify!}
+  ///
+  /// Many optional interfaces are associated with a plugin instance. For
+  /// example, the find in PPP_Find interface receives updates on a per-instance
+  /// basis. This "per-instance" tracking allows such objects to associate
+  /// themselves with an instance as "the" handler for that interface name.
+  ///
+  /// In the case of the find example, the find object registers with its
+  /// associated instance in its constructor and unregisters in its destructor.
+  /// Then whenever it gets updates with a PP_Instance parameter, it can
+  /// map back to the find object corresponding to that given PP_Instance by
+  /// calling GetPerInstanceObject.
+  ///
+  /// This lookup is done on a per-interface-name basis. This means you can
+  /// only have one object of a given interface name associated with an
+  /// instance.
+  ///
+  /// If you are adding a handler for an additional interface, be sure to
+  /// register with the module (AddPluginInterface) for your interface name to
+  /// get the C calls in the first place.
+  ///
+  /// @see RemovePerInstanceObject
+  /// @see GetPerInstanceObject
   void AddPerInstanceObject(const std::string& interface_name, void* object);
 
-  /**
-   * {PENDING: summarize Remove method here}
-   *
-   * @see AddPerInstanceObject
-   */
+  /// {PENDING: summarize Remove method here}
+  ///
+  /// @see AddPerInstanceObject
   void RemovePerInstanceObject(const std::string& interface_name, void* object);
 
-  /**
-   * Look up an object previously associated with an instance. Returns NULL
-   * if the instance is invalid or there is no object for the given interface
-   * name on the instance.
-   *
-   * @see AddPerInstanceObject
-   */
+  /// Look up an object previously associated with an instance. Returns NULL
+  /// if the instance is invalid or there is no object for the given interface
+  /// name on the instance.
+  ///
+  /// @see AddPerInstanceObject
   static void* GetPerInstanceObject(PP_Instance instance,
                                     const std::string& interface_name);
 
@@ -164,8 +265,7 @@ class Instance {
 
 }  // namespace pp
 
-/**
- * @}
- * End addtogroup CPP
- */
+/// @}
+/// End addtogroup CPP
+
 #endif  // PPAPI_CPP_INSTANCE_H_