PPAPI: Clean up documentation for InstanceHandle and PASS_REF

ppapi/cpp/instance_handle.h

 // Copyright (c) 2012 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_CPP_INSTANCE_HANDLE_H_
 #define PPAPI_CPP_INSTANCE_HANDLE_H_
 
 #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 objects' lifetime is managed by the system on the main
+/// thread of the module. This means that it may get destroyed at any time

[dmichael (off chromium), 2012/03/23 21:05:00]

how about if we say "main pepper thread."

[jond, 2012/03/26 16:43:51]

Done.

+/// based on something that happens on the web page. So, it's never good to

[dmichael (off chromium), 2012/03/23 21:05:00]

So->Therefore
?
"never good" doesn't give the right sense here. Maybe "it is not safe to"

[jond, 2012/03/26 16:43:51]

Agreed. I just didn't want to change the technical meaning without someone more
knowledgable looking at it.

On 2012/03/23 21:05:00, dmichael wrote:

+/// 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.
+/// 2. <code>PP_Instance</code> is a good identifier to use for this case.

[dmichael (off chromium), 2012/03/23 21:05:00]

is->would be ?

(If it was a good identifier for this case, we would use it.)

The sense is more <code>PP_Instance</code> is another way to refer to a unique
instance, but we can not use it because it is just a typedef for an integer...

reword as you see fit.

[jond, 2012/03/26 16:43:51]

Changing to "would be" seems okay to me. I made another small modification.

On 2012/03/23 21:05:00, dmichael wrote:

 /// 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).
+/// <code>PP_Instance</code> 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 internal instance handle.

[dmichael (off chromium), 2012/03/23 21:05:00]

"instance handle" -> "PP_Instance"
(not wrong, but confusing since we're in InstanceHandle, but that's not what
you're returning.)

[jond, 2012/03/26 16:43:51]

Done.

+  ///
+  /// @return A <code>PP_Instance</code> internal instance handle.
   PP_Instance pp_instance() const { return pp_instance_; }
 
  private:
   PP_Instance pp_instance_;
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_INSTANCE_HANDLE_H_