PPAPI: Clean up documentation for InstanceHandle and PASS_REF

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

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

1 files changed, 42 insertions, 25 deletions

diff --git a/ppapi/cpp/instance_handle.h b/ppapi/cpp/instance_handle.h
index 941db6e..fd118fd 100644
--- a/ppapi/cpp/instance_handle.h
+++ b/ppapi/cpp/instance_handle.h
@@ -7,46 +7,63 @@
 
 #include "ppapi/c/pp_instance.h"
 
+
+/// @file
+/// This file defines an instance handle used to identify an instance in a
+/// constructor for a resource.
 namespace pp {
 
 class Instance;
 
 /// An instance handle identifies an instance in a constructor for a resource.
-/// Its existence solves two different problems:
+/// This class solves two different problems:
 ///
-/// A pp::Instance objects' lifetime is managed by the system on the main thread
-/// of the plugin. This means that it may get destroyed at any time based on
-/// something that happens on the web page. This means that it's never OK to
-/// refer to a pp::Instance object on a background thread. So we need to pass
-/// some kind of identifier instead to resource constructors so that they may
-/// safely be used on background threads. If the instance becomes invalid, the
-/// resource creation will fail on the background thread, but it won't crash.
+/// 1. A pp::Instance object's lifetime is managed by the system on the main
+/// pepper thread of the module. This means that it may get destroyed at any
+/// time based on something that happens on the web page. Therefore, it's not
+/// safe to refer to a <code>pp::Instance</code> object on a background thread.
+/// Instead, we need to pass some kind of identifier to resource constructors
+/// so that they may safely be used on background threads. If the instance
+/// becomes invalid, the resource creation will fail on the background thread,
+/// but it won't crash.
 ///
-/// Background: PP_Instance would be a good identifier to use for this case.
-/// However, using it in the constructor to resources is problematic.
-/// PP_Instance is just a typedef for an integer, as is a PP_Resource. Many
-/// resources have alternate constructors that just take an existing
-/// PP_Resource, so the constructors would be ambiguous. Having this wrapper
-/// around a PP_Instance prevents this ambiguity, and also gives us a nice
-/// place to consolidate an implicit conversion from pp::Instance* for prettier
-/// code on the main thread (you can just pass "this" to resource constructors
-/// in your instance objects).
+/// 2. <code>PP_Instance</code> would be a good identifier to use for this case.
+/// However, using <code>PP_Instance</code> in the constructor to resources is
+/// problematic because it is just a typedef for an integer, as is a
+/// <code>PP_Resource</code>. Many resources have alternate constructors that
+/// just take an existing <code>PP_Resource</code>, so the constructors would
+/// be ambiguous. Having this wrapper around a <code>PP_Instance</code>
+/// prevents this ambiguity, and also provides a nice place to consolidate an
+/// implicit conversion from <code>pp::Instance*</code> for prettier code on
+/// the main thread (you can just pass "this" to resource constructors in your
+/// instance objects).
 ///
-/// So you should always pass InstanceHandles to background threads instead of
-/// a pp::Instance, and use them in resource constructors and code that may be
-/// used from background threads.
+/// You should always pass an <code>InstanceHandle</code> to background threads
+/// instead of a <code>pp::Instance</code>, and use them in resource
+/// constructors and code that may be used from background threads.
 class InstanceHandle {
  public:
-  /// Implicit constructor for converting a pp::Instance to an instance handle.
+  /// Implicit constructor for converting a <code>pp::Instance</code> to an
+  /// instance handle.
+  ///
+  /// @param[in] instance The instance with which this
+  /// <code>InstanceHandle</code> will be associated.
   InstanceHandle(Instance* instance);
 
-  /// Explicitly convert a PP_Instance to an instance handle. This should not
-  /// be implicit because it can make some resource constructors ambiguous.
-  /// PP_Instance is just a typedef for an integer, as is PP_Resource, so the
-  /// compiler can get confused between the two.
+  /// This constructor explicitly converts a <code>PP_Instance</code> to an
+  /// instance handle. This should not be implicit because it can make some
+  /// resource constructors ambiguous. <code>PP_Instance</code> is just a
+  /// typedef for an integer, as is <code>PP_Resource</code>, so the compiler
+  /// can get confused between the two.
+  ///
+  /// @param[in] pp_instance The instance with which this
+  /// <code>InstanceHandle</code> will be associated.
   explicit InstanceHandle(PP_Instance pp_instance)
       : pp_instance_(pp_instance) {}
 
+  /// The pp_instance() function returns the <code>PP_Instance</code>.
+  ///
+  /// @return A <code>PP_Instance</code> internal instance handle.
   PP_Instance pp_instance() const { return pp_instance_; }
 
  private: