Index: /trunk/src/VBox/Main/idl/VirtualBox.xidl
===================================================================
--- /trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 31260)
+++ /trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 31261)
@@ -8170,4 +8170,12 @@
           with a given timeout in milliseconds; specify -1 for an indefinite wait.
 
+	  Note that the VirtualBox/XPCOM/COM/native event queues of the calling
+	  thread are not processed while waiting.  Neglecting event queues may
+	  have dire consequences (degrade performance, resource hogs,
+	  deadlocks, etc.), this is specially so for the main thread on
+	  platforms using XPCOM.  Callers are adviced wait for short periods
+	  and service their event queues between calls, or to create a worker
+	  thread to do the waiting.
+
         <result name="VBOX_E_IPRT_ERROR">
           Failed to wait for task completion.
@@ -8186,4 +8194,6 @@
           Waits until the given operation is done with a given timeout in
           milliseconds; specify -1 for an indefinite wait.
+
+	  See <link to="#waitForCompletion"> for event queue considerations.
 
         <result name="VBOX_E_IPRT_ERROR">