New documentation for resource.h, core.h, and common.h

ppapi/cpp/resource.h

Index: ppapi/cpp/resource.h
===================================================================
--- ppapi/cpp/resource.h	(revision 87784)
+++ ppapi/cpp/resource.h	(working copy)
@@ -7,41 +7,66 @@
 
 #include "ppapi/c/pp_resource.h"
 
+/// @file
+/// This file defines a Resource type representing data associated
+/// with the module.
 namespace pp {
 
-// Base class for refcounted plugin resources.
+/// A reference counted module resource.
 class Resource {
  public:
+
+  /// The default constructor.
   Resource();
+
+  /// A constructor accepting a reference to a Resource.

[dmichael (off chromium), 2011/06/07 05:01:23]

You can just say 'The copy constructor.'

[jond, 2011/06/07 16:41:00]

I changed this to "A constructor fo copying a resource" only because in other
places, I start this sentence "A constructor..." and I didn't want to have to
rewrite all of them.

[dmichael (off chromium), 2011/06/07 20:45:26]

Above it says 'The default constructor.'  The copy constructor is special as
well, and is called 'The copy constructor'.  I think wording it otherwise is
more confusing than helpful.

+  ///
+  /// @param[in] other A Resource.
   Resource(const Resource& other);
 
+  /// Destructor.
   virtual ~Resource();
 
+  /// This function assigns one Resource to another Resource.
+  ///
+  /// @param[in] other A Resource.
+  /// @return A Resource containing the assigned Resource.
   Resource& operator=(const Resource& other);
 
-  // Returns true if the given resource is invalid or uninitialized.
+  /// This functions determiens if this resource is invalid or

[dmichael (off chromium), 2011/06/07 05:01:23]

I liked the original wording a little better.  if you leave it this way, fix
'determiens'

[jond, 2011/06/07 16:41:00]

I'm trying to be consistent and all these sentences start out "This function..."

- Jon

On 2011/06/07 05:01:23, dmichael1 wrote:

+  /// uninitialized.
+  ///
+  /// @return true if this resource is invalid or uninitialized.
   bool is_null() const { return !pp_resource_; }
 
   PP_Resource pp_resource() const { return pp_resource_; }
 
-  // Releases ownership of the PP_Resource and returns it to the caller.
-  // Note the the reference count on the resource is unchanged and the caller
-  // needs to release the resource.
+  /// This function releases ownership of this reource and returns it to the

[dmichael (off chromium), 2011/06/07 05:01:23]

reource->resource

[jond, 2011/06/07 16:41:00]

Done.

[jond, 2011/06/07 16:41:00]

Done.

+  /// caller.
+  ///
+  /// Note that the reference count on the resource is unchanged and the caller
+  /// needs to release the resource.
+  ///
+  /// @return The detached PP_Resource.
   PP_Resource detach();
 
  protected:
-  // This constructor is used when we've gotten a PP_Resource as a return value
-  // that we need to addref.
+  /// A constructer used when a PP_Resource is provided as a return value

[dmichael (off chromium), 2011/06/07 05:01:23]

constructer->constructor

[jond, 2011/06/07 16:41:00]

Done.

+  /// that we need to provide a reference.

[dmichael (off chromium), 2011/06/07 05:01:23]

change to 'whose reference count we need to increment.'

[jond, 2011/06/07 16:41:00]

Done.

[jond, 2011/06/07 16:41:00]

Done.

+  ///
+  /// @param[in] resource A PP_Resource.
   explicit Resource(PP_Resource resource);
 
-  // Called by derived class' constructors to initialize this Resource with
-  // a PP_Resource that has already been AddRef'ed. It also assumes this object
-  // has no current resource.
-  //
-  // The intended usage is that the derived class constructor will call the
-  // default Resource constructor, then make a call to create a resource. It
-  // then wants to assign the new resource (which, since it was returned by the
-  // browser, is already AddRef'ed).
+  /// This function is called by derived class' constructors to initialize this
+  /// Resource with a PP_Resource that has already received a reference using

[dmichael (off chromium), 2011/06/07 05:01:23]

'received a reference'->'had its reference count incremented'

[jond, 2011/06/07 16:41:00]

Done.

[jond, 2011/06/07 16:41:00]

Done.

+  /// Core::AddRefResource. It also assumes this object has no current resource.
+  ///
+  /// The intended usage is that the derived class constructor will call the
+  /// default Resource constructor, then make a call to create a resource. It
+  /// then wants to assign the new resource (which, since it was returned by the
+  /// browser, is already AddRef'ed).
+  ///
+  /// @param[in] resource A PP_Resource.
   void PassRefFromConstructor(PP_Resource resource);
 
  private: