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

ppapi/c/ppb_core.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_PPB_CORE_H_
 #define PPAPI_C_PPB_CORE_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
@@ skipping 85 matching lines @@
 
   /**
    * CallOnMainThread is a pointer to a function that schedules work to be
    * executed on the main module thread after the specified delay. The delay
    * may be 0 to specify a call back as soon as possible.
    *
    * The |result| parameter will just be passed as the second argument to the
    * callback. Many applications won't need this, but it allows a plugin to
    * emulate calls of some callbacks which do use this value.
    *
+   * NOTE: CallOnMainThread, even when used from the main thread with a delay
+   * of 0 milliseconds, will never directly invoke the callback.  Even in this
+   * case, the callback will be scheduled asynchronously.
+   *
    * NOTE: If the browser is shutting down or if the plugin has no instances,
    * then the callback function may not be called.
    *
    * @param[in] delay_in_milliseconds An int32_t delay in milliseconds.
    * @param[in] callback A PP_CompletionCallback callback function that the
    * browser will call after the specified delay.
    * @param[in] result An int32_t that the browser will pass to the given
    * PP_CompletionCallback.
    */
   void (*CallOnMainThread)(int32_t delay_in_milliseconds,
@@ skipping 12 matching lines @@
    */
   PP_Bool (*IsMainThread)();
 };
 /**
  * @}
  */
 
 
 #endif  /* PPAPI_C_DEV_PPB_CORE_DEV_H_ */