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

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

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

3 files changed, 120 insertions, 34 deletions

diff --git a/ppapi/cpp/common.h b/ppapi/cpp/common.h
index 8f1c5ee..1531ae1 100644
--- a/ppapi/cpp/common.h
+++ b/ppapi/cpp/common.h
@@ -1,38 +1,35 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Copyright (c) 2011 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_COMMON_H_
 #define PPAPI_CPP_COMMON_H_
 
-/**
- * @file
- * Defines the API ...
- *
- * @addtogroup CPP
- * @{
- */
+
+/// @file
+/// Defines the API to convert PP_Bool to and from their C++ equivalent.
 
 #include "ppapi/c/pp_bool.h"
 
 namespace pp {
 
-/** Convert a C++ bool to the appropriate PP_Bool value. */
+/// This function is used to convert a C++ bool to the appropriate PP_Bool
+/// value.
+/// @param[in] value A C++ boolean value.
+/// @return A PP_Bool equivalent of the C++ boolean value.
 inline PP_Bool BoolToPPBool(bool value) {
   return value ? PP_TRUE : PP_FALSE;
 }
 
-/** Convert a PP_Bool to a C++ bool value. */
+/// This function is used to convert a PP_Bool to a C++ boolean value.
+/// value.
+/// @param[in] value A PP_Bool boolean value.
+/// @return A C++ equivalent of the PP_Bool boolean value.
 inline bool PPBoolToBool(PP_Bool value) {
   return !!value;
 }
 
 }  // namespace pp
 
-/**
- * @}
- * End addtogroup CPP
- */
-
 #endif  // PPAPI_CPP_COMMON_H_
 
diff --git a/ppapi/cpp/core.h b/ppapi/cpp/core.h
index 7f0fefc..6ceebf5 100644
--- a/ppapi/cpp/core.h
+++ b/ppapi/cpp/core.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Copyright (c) 2011 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.
 
@@ -7,45 +7,108 @@
 
 #include "ppapi/c/ppb_core.h"
 
+/// @file
+/// This file defines APIs related to memory management, time, and threads.
+
 namespace pp {
 
 class CompletionCallback;
 class Module;
 
-// Simple wrapper around the PPB_Core interface. Some of these wrappers add
-// nothing over the C interface, but some allow the use of C++ arguments.
+/// APIs related to memory management, time, and threads.
 class Core {
  public:
   // Note that we explicitly don't expose Resource& versions of this function
   // since Resource will normally manage the refcount properly. These should
   // be called only when doing manual management on raw PP_Resource handles,
   // which should be fairly rare.
+
+  /// A function that increments the reference count for the provided resource.
+  ///
+  /// @param[in] resource A PP_Resource containing the resource.
   void AddRefResource(PP_Resource resource) {
     interface_->AddRefResource(resource);
   }
+
+  /// A function that decrements the reference count for the provided resource.
+  /// The resource will be deallocated if the reference count reaches zero.
+  ///
+  /// @param[in] resource A PP_Resource containing the resource.
   void ReleaseResource(PP_Resource resource) {
     interface_->ReleaseResource(resource);
   }
 
+  /// A function that allocates memory.
+  ///
+  /// @param[in] @param[in] num_bytes A number of bytes to allocate.
+  /// @return A pointer to the memory if successful, NULL If the
+  /// allocation fails.
   void* MemAlloc(uint32_t num_bytes) {
     return interface_->MemAlloc(num_bytes);
   }
+
+  /// A function that deallocates memory.
+  ///
+  /// @param[in] ptr A pointer to the memory to deallocate. It is safe to
+  /// pass NULL to this function.
   void MemFree(void* ptr) {
     interface_->MemFree(ptr);
   }
 
+  /// A function that that returns the "wall clock time" according to the
+  /// browser.
+  ///
+  /// @return A PP_Time containing the "wall clock time" according to the
+  /// browser.
   PP_Time GetTime() {
     return interface_->GetTime();
   }
 
+  /// A function that that returns the "tick time" according to the browser.
+  /// This clock is used by the browser when passing some event times to the
+  /// plugin (e.g., via the PP_InputEvent::time_stamp_seconds field). It is
+  /// not correlated to any actual wall clock time (like GetTime()). Because
+  /// of this, it will not change if the user changes their computer clock.
+  ///
+  /// @return A PP_TimeTicks containing the "tick time" according to the
+  /// browser.
   PP_TimeTicks GetTimeTicks() {
     return interface_->GetTimeTicks();
   }
 
+  /// A function that schedules work to be executed on the main pepper thread
+  /// after the specified delay. The delay may be 0 to specify a call back as
+  /// soon as possible.
+  ///
+  /// The |result| parameter will just be passed as the second argument to the
+  /// callback. Many applications won't need this, but it allows a plugin to
+  /// emulate calls of some callbacks which do use this value.
+  ///
+  /// NOTE: CallOnMainThread, even when used from the main thread with a delay
+  /// of 0 milliseconds, will never directly invoke the callback.  Even in this
+  /// case, the callback will be scheduled asynchronously.
+  ///
+  /// NOTE: If the browser is shutting down or if the plugin has no instances,
+  /// then the callback function may not be called.
+  ///
+  /// @param[in] delay_in_milliseconds An int32_t delay in milliseconds.
+  /// @param[in] callback A CompletionCallback callback function that the
+  /// browser will call after the specified delay.
+  /// @param[in] result An int32_t that the browser will pass to the given
+  /// CompletionCallback.
   void CallOnMainThread(int32_t delay_in_milliseconds,
                         const CompletionCallback& callback,
                         int32_t result = 0);
 
+
+  /// A function that returns true if the current thread is the main pepper
+  /// thread.
+  ///
+  /// This function is useful for implementing sanity checks, and deciding if
+  /// dispatching using CallOnMainThread() is required.
+  ///
+  /// @return A PP_BOOL containing PP_TRUE if the current thread is the main
+  /// pepper thread, otherwise PP_FALSE.
   bool IsMainThread();
 
  private:
diff --git a/ppapi/cpp/resource.h b/ppapi/cpp/resource.h
index c59b37d..8d22254 100644
--- a/ppapi/cpp/resource.h
+++ b/ppapi/cpp/resource.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Copyright (c) 2011 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.
 
@@ -7,41 +7,67 @@
 
 #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 for copying a resource.
+  ///
+  /// @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 determines if this resource is invalid or
+  /// 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 resource and returns it to the
+  /// 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 constructor used when a PP_Resource is provided as a return value
+  /// whose reference count we need to increment.
+  ///
+  /// @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 had its reference count
+  /// incremented by 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: