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

1 files changed, 31 insertions, 18 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);
 /**