Add some more documentation from a recent ppapi discussion....

ppapi/c/pp_completion_callback.h

 /* Copyright (c) 2010 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
  * Defines the API ...
@@ skipping 14 matching lines @@
  */
 
 /**
  * @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_Error_WouldBlock to indicate when the method will complete
- * asynchronously.  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.
+ * 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.
  *
  * 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.
  */
 struct PP_CompletionCallback {
   PP_CompletionCallback_Func func;
   void* user_data;
 };
 /**
@@ skipping 40 matching lines @@
  */
 PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() {
   return PP_MakeCompletionCallback(NULL, NULL);
 }
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PP_COMPLETION_CALLBACK_H_ */