Index: ppapi/c/pp_completion_callback.h |
=================================================================== |
--- ppapi/c/pp_completion_callback.h (revision 90368) |
+++ ppapi/c/pp_completion_callback.h (working copy) |
@@ -21,8 +21,14 @@ |
*/ |
/** |
- * PP_CompletionCallback_Func defines the signature that you implement to |
+ * This typedef defines the signature that you implement to |
* receive callbacks on asynchronous completion. |
+ * |
+ * @param[in] user_data A pointer to user data passed to a callback function. |
+ * @param[in] result 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. |
dmichael (off chromium)
2011/06/27 15:45:41
I know this is not your wording here, but I don't
jond
2011/06/29 21:14:38
Polinia mentioned that -1 isn't really a an error,
|
*/ |
typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result); |
/** |
@@ -35,22 +41,30 @@ |
*/ |
/** |
- * Any method that takes a PP_CompletionCallback has the option of completing |
- * asynchronously if the operation would block. Such a method should return |
- * PP_OK_COMPLETIONPENDING to indicate that the method will complete |
- * 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. |
+ * Any method that takes a <code>PP_CompletionCallback</code> has the option of |
+ * completing asynchronously if the operation would block. Such a method |
+ * should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the |
+ * method will complete 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. |
+ * <code>PP_BlockUntilComplete()</code> provides a convenient way to specify |
+ * blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more |
+ * 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 |
+ * indicate if the call will complete 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 { |
+ /** |
+ * This value is a callback function that will be called. |
+ */ |
PP_CompletionCallback_Func func; |
+ |
+ /** |
+ * This value is a pointer to user data passed to a callback function. |
+ */ |
void* user_data; |
}; |
/** |
@@ -63,13 +77,14 @@ |
*/ |
/** |
- * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback. |
+ * This function is used to create a <code>PP_CompletionCallback</code>. |
dmichael (off chromium)
2011/06/27 15:45:41
I was fine with the old wording of 'PP_MakeComplet
jond
2011/06/29 21:14:38
Done.
jond
2011/06/29 21:14:38
Done.
|
* |
- * @param[in] func A PP_CompletionCallback_Func that will be called. |
+ * @param[in] func A <code>PP_CompletionCallback_Func</code> 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. |
+ * @return A <code>PP_CompletionCallback</code> structure. |
*/ |
PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback( |
PP_CompletionCallback_Func func, |
@@ -89,9 +104,10 @@ |
*/ |
/** |
- * PP_RunCompletionCallback() is used to run a callback. |
+ * This function is used to run a callback. |
* |
- * @param[in] cc A pointer to a PP_CompletionCallback that will be run. |
+ * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> 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 |
@@ -112,29 +128,28 @@ |
*/ |
/** |
- * PP_BlockUntilComplete() is used in place of an actual completion callback |
+ * This function 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. |
+ * @return A <code>PP_CompletionCallback</code> structure. |
*/ |
PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() { |
return PP_MakeCompletionCallback(NULL, NULL); |
} |
/** |
- * Runs a callback and clears the reference to it. |
+ * This function runs a callback and clears the reference to that callback. |
* |
- * This is used when the null-ness of a completion callback is used as a signal |
- * for whether a completion callback has been registered. In this case, after |
- * the execution of the callback, it should be cleared. |
- * |
- * However, this introduces a conflict if the completion callback wants to |
- * schedule more work that involves the same completion callback again (for |
- * example, when reading data from an URLLoader, one would typically queue up |
+ * This function is used when the null-ness of a completion callback is used as |
+ * a signal for whether a completion callback has been registered. In this |
+ * case, after the execution of the callback, it should be cleared. However, |
+ * this introduces a conflict if the completion callback wants to schedule more |
+ * work that involves the same completion callback again (for example, when |
+ * reading data from an URLLoader, one would typically queue up |
* another read callback). As a result, this function clears the pointer |
- * *before* the given callback is executed. |
+ * before the provided callback is executed. |
*/ |
PP_INLINE void PP_RunAndClearCompletionCallback( |
struct PP_CompletionCallback* cc, |