Documentation improvements: Lwt_main.run and Lwt_io.wait_read/wait_wr…

…ite (#547)

src/unix/lwt_main.mli

@@ -24,9 +24,26 @@
 (** This module controls the ``main-loop'' of Lwt. *)
 
 val run : 'a Lwt.t -> 'a
-  (** [run t] calls the Lwt scheduler repeatedly until [t] terminates,
-      then returns the value returned by the thread. If [t] fails with
-      an exception, this exception is raised.
+  (** [run p] calls the Lwt scheduler repeatedly until [p] resolves,
+      and returns the value of [p] if it is fulfilled. If [p] is rejected with
+      an exception, that exception is raised.
+
+      Every native or bytecode program that uses Lwt should always use
+      this function for evaluating a promise at the top level
+      (such as its main function or main loop),
+      otherwise promises that depend on I/O operations will not be resolved.
+
+      Example:
+      {[
+let main () = Lwt_io.write_line Lwt_io.stdout "hello world"
+
+let () = Lwt_main.run @@ main ()
+      ]}
+
+      When targeting JavaScript, [Lwt_main.run] is not available,
+      but neither it's necessary since
+      the JS environment automatically takes care of the I/O considerations.
+
 
       Note that you should avoid using [run] inside threads
       - The calling threads will not resume before [run]

src/unix/lwt_unix.cppo.mli

@@ -503,12 +503,27 @@ val writable : file_descr -> bool
       writable. *)
 
 val wait_read : file_descr -> unit Lwt.t
-  (** waits (without blocking other threads) until there is something
-      to read on the file descriptor *)
+  (** Waits (without blocking other threads) until there is something
+      to read from the file descriptor.
+
+      Note that you don't need to use this function if you are
+      using Lwt I/O functions for reading, since they provide
+      non-blocking waiting automatically.
+
+      The intended use case for this function is interfacing with
+      existing libraries that are known to be blocking. *)
 
 val wait_write : file_descr -> unit Lwt.t
-  (** waits (without blocking other threads) until it is possible to
-      write on the file descriptor *)
+  (** Waits (without blocking other threads) until it is possible to
+      write on the file descriptor.
+
+      Note that you don't need to use this function if you are
+      using Lwt I/O functions for writing, since they provide
+      non-blocking waiting automatically.
+
+      The intended use case for this function is interfacing with
+      existing libraries that are known to be blocking. *)
+
 
 (** {2 Seeking and truncating} *)