direct: rewrite some parts of the documentation

raphael-proust · raphael-proust · commit 87227101a17e · 2025-09-05T15:48:22.000+02:00
diff --git a/src/direct/lwt_direct.mli b/src/direct/lwt_direct.mli
@@ -1,46 +1,52 @@
 (** Direct style control flow for Lwt.
 
-    This module relies on OCaml 5's
-    {{:https://ocaml.org/manual/5.3/effects.html} effect handlers}.
-    Instead of chaining promises using {!Lwt.bind} and {!Lwt.map}
-    and other combinators, it becomes possible to start
-    lightweight "tasks" using [Lwt_direct.spawn (fun () -> ...)].
-    The body of such a task is written in direct-style code,
-    using OCaml's standard control flow structures such as loops,
-    higher-order functions, exception handlers, [match], etc.
-
-    Interactions with the rest of lwt can be done using [await],
-    for example:
+    Using this module you can write code in direct style (using loops,
+    exceptions handlers, etc.) in an Lwt codebase. Your direct-style sections
+    must be enclosed in a call to {!spawn} and they may {!await} on promises.
+    For example:
 
     {[
-    Lwt_direct.spawn (fun () ->
+    open Lwt_direct
+    spawn (fun () ->
       let continue = ref true in
       while !continue do
-        match Lwt_io.read_line in_channel |> Lwt_direct.await with
+        match await @@ Lwt_io.read_line in_channel with
         | exception End_of_file -> continue := false
         | line ->
           let uppercase_line = String.uppercase_ascii line in
-          Lwt_io.write_line out_channel uppercase_line |> Lwt_direct.await
+          await @@ Lwt_io.write_line out_channel uppercase_line
       done)
     ]}
 
-    This code snippet contains a simple "task" that repeatedly reads
-    a line from a [Lwt_io] channel, uppercases it, and writes the
-    uppercase version to another channel.
+    In this code snippet, the [while]-loop repeats a simple task of reading from
+    an {!Lwt_io.channel}, modifying it, and writing it to a different channel.
+    The code is in direct-style: the control structures are standard OCaml
+    without any Lwt primitives.
 
-    This task is itself a [unit Lwt.t], which is resolved when the function
-    returns. It is possible to use
-    {!Lwt_direct.run_in_the_background} to ignore the result and
-    let the task run in the background instead.
+    The code-snippet as a whole is a [unit Lwt.t] promise. It becomes resovled
+    when the function returns. Conversely, the promises inside the snippet are
+    wrapped in {!await}, turning them into regular plain (non-Lwt) values
+    (although values that are not available immediately).
 
-    *)
+    The [Lwt_direct] module is implemented using OCaml 5's
+    {{:https://ocaml.org/manual/5.3/effects.html} effects and effect handlers}.
+    This allows the kind of scheduling where a promise is turned into a regular
+    value and vice-versa. *)
 
 val spawn : (unit -> 'a) -> 'a Lwt.t
-(** [spawn f] runs the function [f ()] in a task within
-    the [Lwt_unix] event loop. [f ()] can create [Lwt]
-    promises and use {!await} to wait for them. Like any promise
-    in Lwt, [f ()] can starve the event loop if it runs long computations
-    without yielding to the event loop.
+(** [spawn f] runs the function [f ()], it also returns a promise [p] which is
+    resolved when the call to [f ()] returns a value. If [f ()] throws an
+    exception, the promise [p] is rejected.
+
+    The function [f] can create Lwt promises (e.g., by calling functions from
+    [Lwt_io], [Lwt_unix], or third-party libraries) and use {!await} to wait for
+    them. These promises are evaluated in the Lwt event loop.
+
+    Like any promise in Lwt, [f ()] can starve the event loop if it runs long
+    computations without yielding to the event loop.
+
+    Cancelling the promise returned by [spawn] has no effect: the execution of
+    [f ()] continues and the promise is not cancelled.
 
     When [f ()] terminates (successfully or not), the promise
     [spawn f] is resolved with [f ()]'s result, or the exception
@@ -50,32 +56,43 @@ val spawn_in_the_background :
   (unit -> unit) ->
   unit
 (** [spawn_in_the_background f] is similar to [ignore (spawn f)].
-    The computation [f()] runs in the background in the event loop
+    The computation [f ()] runs in the background in the event loop
     and returns no result.
+
     If [f()] raises an exception, {!Lwt.async_exception_hook} is called. *)
 
 val yield : unit -> unit
 (** Yield to the event loop.
 
-    Calling [yield] outside of {!spawn} or {!run_in_the_background} will raise an exception,
-    crash your program, or otherwise cause errors. It is a programming error to do so. *)
+    This is similar to [await (Lwt.pause ())], using less indirection internally
+    and fewer characters to write.
+
+    Calling [yield] outside of {!spawn} or {!spawn_in_the_background} will raise
+    an exception, crash your program, or otherwise cause errors. It is a
+    programming error to do so. *)
 
 val await : 'a Lwt.t -> 'a
-(** [await prom] returns the result of [prom], or re-raises the
-    exception with which [prom] failed if it failed.
-    If [prom] is not resolved yet, [await prom] will suspend the
-    current task and resume it when [prom] is resolved.
+(** [await p] returns the result of [p] (or raises the exception with which [p]
+    was rejected.
+
+    If [p] is not resolved yet, [await p] will suspend the current task (i.e.,
+    the computation started by the surrounding {!spawn}) and resume it when [p]
+    is resolved.
 
-    Calling [await] outside of {!spawn} or {!run_in_the_background} will raise an exception,
-    crash your program, or otherwise cause errors. It is a programming error to do so. *)
+    Calling [await] outside of {!spawn} or {!spawn_in_the_background} will raise
+    an exception, crash your program, or otherwise cause errors. It is a
+    programming error to do so. *)
 
 (** Local storage.
 
     This storage is the same as the one described with {!Lwt.key},
     except that it is usable from the inside of {!spawn} or
-    {!run_in_the_background}.
+    {!spawn_in_the_background}.
+
+    Each task has its own storage, independent from other tasks or promises.
 
-    Each task has its own storage, independent from other tasks or promises. *)
+    NOTE: it is recommended to use [Lwt_direct.Storage] functions rather than
+    [Lwt.key] functions from {!Lwt}. The latter is deprecated. *)
 module Storage : sig
   type 'a key = 'a Lwt.key
   val new_key : unit -> 'a key
