Document Lwt.pause semantics in Lwt_main

Author: Christopher Zimmermann

src/unix/lwt_main.mli

@@ -40,7 +40,12 @@ let () = Lwt_main.run (main ())
       error (i.e., code making such a call is inherently broken).
 
       It is not safe to call [Lwt_main.run] in a function registered with
-      [Pervasives.at_exit], use {!Lwt_main.at_exit} instead. *)
+      [Pervasives.at_exit], use {!Lwt_main.at_exit} instead.
+
+      [Lwt.pause] allows the scheduler to run other promises before fulfilling
+      the returned promise. To process all pending IO and allow all pending
+      threads to run one currently needs to need to call Lwt.pause twice:
+      [Lwt.pause () >>= Lwt.pause] *)
 
 val yield : unit -> unit Lwt.t [@@deprecated "Use Lwt.pause instead"]
   (** [yield ()] is a pending promise that is fulfilled after Lwt finishes