New and updated docs for pp_completion_callback

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

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

1 files changed, 43 insertions, 16 deletions

diff --git a/ppapi/c/pp_completion_callback.h b/ppapi/c/pp_completion_callback.h
index 9fbe71b..927b185 100644
--- a/ppapi/c/pp_completion_callback.h
+++ b/ppapi/c/pp_completion_callback.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,7 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the API to create and run a callback.
  */
 
 #include <stdlib.h>
@@ -19,6 +19,11 @@
  * @addtogroup Typedefs
  * @{
  */
+
+/**
+ * PP_CompletionCallback_Funct defines the signature that you implmeent to
+ * receive callbacks on asynchronous completion.
+ */
 typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
 /**
  * @}
@@ -33,17 +38,16 @@ typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
  * Any method that takes a PP_CompletionCallback has the option of completing
  * asynchronously if the operation would block.  Such a method should return
  * PP_ERROR_WOULDBLOCK to indicate that the method will complete
- * asynchronously.  In this case it will signal completion by invoking the
- * supplied completion callback, which will always be invoked from the main
- * PPAPI thread of execution.  If the method returns any other value,
- * including PP_OK, the completion callback will not be invoked.  If the
- * completion callback is NULL, then the method will block if necessary to
- * complete its work.  PP_BlockUntilComplete() provides a convenient way to
- * specify blocking behavior.
+ * asynchronously and will always be invoked from the main thread of PPAPI
+ * execution.  If the completion callback is NULL, then the operation will
+ * block if necessary to complete its work.  PP_BlockUntilComplete() provides a
+ * convenient way to specify blocking behavior. Refer to PP_BlockUntilComplete
+ * for more information.
  *
- * The result parameter passes an int32_t that if negative indicates an error
- * code.  Otherwise the result value indicates success.  If it is a positive
- * value then it may carry additional information.
+ * The result parameter passes an int32_t that, if negative or equal to 0,
+ * indicate if the call will completely asynchronously (the callback will be
+ * called with a status code). A value greater than zero indicates additional
+ * information such as bytes read.
  */
 struct PP_CompletionCallback {
   PP_CompletionCallback_Func func;
@@ -57,6 +61,16 @@ struct PP_CompletionCallback {
  * @addtogroup Functions
  * @{
  */
+
+/**
+ * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback.
+ *
+ * @param[in] func A PP_CompletionCallback_Func that will be called.
+ * @param[in] user_data A pointer to user data passed to your callback
+ * function. This is optional and is typically used to help track state
+ * when you may have multiple callbacks pending.
+ * @return A PP_CompletionCallback structure.
+ */
 PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
     PP_CompletionCallback_Func func,
     void* user_data) {
@@ -73,6 +87,16 @@ PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback(
  * @addtogroup Functions
  * @{
  */
+
+/**
+ * PP_RunCompletionCallback() is used to run a callback.
+ *
+ * @param[in] cc A pointer to a PP_CompletionCallback that will be run.
+ * @param[in] res The result parameter that, if negative or equal to 0,
+ * indicate if the call will completely asynchronously (the callback will be
+ * called with a status code). A value greater than zero indicates additional
+ * information such as bytes read.
+ */
 PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
                                         int32_t res) {
   cc->func(cc->user_data, res);
@@ -86,10 +110,13 @@ PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
  * @{
  */
 
-/**
- * Use this in place of an actual completion callback to request blocking
- * behavior.  If specified, the calling thread will block until a method
- *  completes.  This is only usable from background threads.
+ /**
+ * PP_BlockUntilComplete() is used in place of an actual completion callback
+ * to request blocking behavior. If specified, the calling thread will block
+ * until the function completes.  Blocking completion callbacks are only usable
+ * from background threads.
+ *
+ * @return A PP_CompletionCallback structure.
  */
 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() {
   return PP_MakeCompletionCallback(NULL, NULL);