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
diff --git a/ppapi/c/pp_completion_callback.h b/ppapi/c/pp_completion_callback.h
index 9fbe71b7..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 @@
* 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 @@
* @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 @@
* @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 @@
* @{
*/
-/**
- * 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);
