Mostly minor changes such as adding <code></code> around elements, a little rewriting, and a few ...

ppapi/c/pp_completion_callback.h

 /* 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_C_PP_COMPLETION_CALLBACK_H_
 #define PPAPI_C_PP_COMPLETION_CALLBACK_H_
 
 /**
  * @file
  * This file defines the API to create and run a callback.
  */
 
 #include <stdlib.h>
 
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_stdint.h"
 
 /**
  * @addtogroup Typedefs
  * @{
  */
 
 /**
- * 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 think it's right.  By the time
you get the callback, I think the operation has already completed (or not), and
negative values are an indication of error.  The wording sounds closer to the
meaning of the return value for a function that accepts a PP_CompletionCallback
parameter.  Here's a swing at rewording, though you may want to check with
Polina:

If result is 0 (PP_OK), the operation succeeded.  Negative values indicate error
and are specified in pp_errors.h.  Positive values for result usually indicate
success and have some operation-dependent meaning (such as bytes read).

[jond, 2011/06/29 21:14:38]

Polinia mentioned that -1 isn't really a an error, so I mentioned it.

On 2011/06/27 15:45:41, dmichael1 wrote:

  */
 typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result);
 /**
  * @}
  */
 
 /**
  * @addtogroup Structs
  * @{
  */
 
 /**
- * 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;
 };
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
 
 /**
- * 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_MakeCompletionCallback()'. Is 'This
function' a new convention?  I'm happy with it either way; I just want to make
sure you're not changing them on my account. My beef was with 'Func is a pointer
to a function'; mostly the 'is a pointer to a function' part.

[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,
     void* user_data) {
   struct PP_CompletionCallback cc;
   cc.func = func;
   cc.user_data = user_data;
   return cc;
 }
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
 
 /**
- * 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
  * information such as bytes read.
  */
 PP_INLINE void PP_RunCompletionCallback(struct PP_CompletionCallback* cc,
                                         int32_t res) {
   cc->func(cc->user_data, res);
 }
 
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
 
  /**
- * 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,
     int32_t res) {
   struct PP_CompletionCallback temp = *cc;
   *cc = PP_BlockUntilComplete();
   PP_RunCompletionCallback(&temp, res);
 }
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PP_COMPLETION_CALLBACK_H_ */