Clean up documentation

The only API change is that `Hook` is now inlined into `Switch`,
as that was its only user.

Some things have been reordered to present them in a better order.
Most modules now have more documentation, and often an example.

lib_eio/eio.ml

@@ -1,6 +1,5 @@
 open Effect
 
-module Hook = Hook
 module Cancel = Cancel
 
 module Private = struct

lib_eio/switch.ml

@@ -1,3 +1,7 @@
+type hook = Hook.t
+let remove_hook = Hook.remove
+let null_hook = Hook.null
+
 type t = {
   id : Ctf.id;
   mutable fibres : int;

lib_eio/utils/eio_utils.ml

@@ -0,0 +1,8 @@
+(** Utilities for implementing Eio event loops.
+
+    These aren't intended for users of Eio. *)
+
+module Lf_queue = Lf_queue
+module Suspended = Suspended
+module Trace = Trace
+module Zzz = Zzz

lib_eio/utils/suspended.ml

@@ -1,3 +1,5 @@
+(** A suspended fibre with its context. *)
+
 open Eio.Private.Effect.Deep
 
 type 'a t = {

lib_eio/utils/trace.mli

@@ -1,3 +1,5 @@
+(** The default implementation of {!Eio.traceln}. *)
+
 val mutex : Mutex.t
 
 val default_traceln :

lib_eio/utils/zzz.mli

@@ -1,3 +1,5 @@
+(** A set of timers. *)
+
 module Key : sig
   type t
 end

lib_eio_linux/eio_linux.ml

@@ -47,7 +47,7 @@ module FD = struct
   type t = {
     seekable : bool;
     close_unix : bool;                          (* Whether closing this also closes the underlying FD. *)
-    mutable release_hook : Eio.Hook.t;          (* Use this on close to remove switch's [on_release] hook. *)
+    mutable release_hook : Eio.Switch.hook;     (* Use this on close to remove switch's [on_release] hook. *)
     mutable fd : [`Open of Unix.file_descr | `Closed]
   }
 
@@ -63,7 +63,7 @@ module FD = struct
     Ctf.label "close";
     let fd = get "close" t in
     t.fd <- `Closed;
-    Eio.Hook.remove t.release_hook;
+    Eio.Switch.remove_hook t.release_hook;
     if t.close_unix then (
       let res = perform (Close fd) in
       Log.debug (fun l -> l "close: woken up");
@@ -85,19 +85,19 @@ module FD = struct
     | `Peek -> fd
     | `Take ->
       t.fd <- `Closed;
-      Eio.Hook.remove t.release_hook;
+      Eio.Switch.remove_hook t.release_hook;
       fd
 
   let of_unix_no_hook ~seekable ~close_unix fd =
-    { seekable; close_unix; fd = `Open fd; release_hook = Eio.Hook.null }
+    { seekable; close_unix; fd = `Open fd; release_hook = Eio.Switch.null_hook }
 
   let of_unix ~sw ~seekable ~close_unix fd =
     let t = of_unix_no_hook ~seekable ~close_unix fd in
     t.release_hook <- Switch.on_release_cancellable sw (fun () -> ensure_closed t);
     t
 
   let placeholder ~seekable ~close_unix =
-    { seekable; close_unix; fd = `Closed; release_hook = Eio.Hook.null }
+    { seekable; close_unix; fd = `Closed; release_hook = Eio.Switch.null_hook }
 
   let uring_file_offset t =
     if t.seekable then Optint.Int63.minus_one else Optint.Int63.zero

lib_eio_luv/eio_luv.ml

@@ -136,7 +136,7 @@ module Low_level = struct
 
   module Handle = struct
     type 'a t = {
-      mutable release_hook : Eio.Hook.t;        (* Use this on close to remove switch's [on_release] hook. *)
+      mutable release_hook : Eio.Switch.hook;        (* Use this on close to remove switch's [on_release] hook. *)
       mutable fd : [`Open of 'a Luv.Handle.t | `Closed]
     }
 
@@ -152,7 +152,7 @@ module Low_level = struct
       Ctf.label "close";
       let fd = get "close" t in
       t.fd <- `Closed;
-      Eio.Hook.remove t.release_hook;
+      Eio.Switch.remove_hook t.release_hook;
       enter_unchecked @@ fun t k ->
       Luv.Handle.close fd (enqueue_thread t k)
 
@@ -162,7 +162,7 @@ module Low_level = struct
     let to_luv x = get "to_luv" x
 
     let of_luv_no_hook fd =
-      { fd = `Open fd; release_hook = Eio.Hook.null }
+      { fd = `Open fd; release_hook = Eio.Switch.null_hook }
 
     let of_luv ~sw fd =
       let t = of_luv_no_hook fd in
@@ -178,13 +178,13 @@ module Low_level = struct
         | `Peek -> Some fd
         | `Take ->
           t.fd <- `Closed;
-          Eio.Hook.remove t.release_hook;
+          Eio.Switch.remove_hook t.release_hook;
           Some fd
   end
 
   module File = struct
     type t = {
-      mutable release_hook : Eio.Hook.t;        (* Use this on close to remove switch's [on_release] hook. *)
+      mutable release_hook : Eio.Switch.hook;        (* Use this on close to remove switch's [on_release] hook. *)
       mutable fd : [`Open of Luv.File.t | `Closed]
     }
 
@@ -200,7 +200,7 @@ module Low_level = struct
       Ctf.label "close";
       let fd = get "close" t in
       t.fd <- `Closed;
-      Eio.Hook.remove t.release_hook;
+      Eio.Switch.remove_hook t.release_hook;
       await_exn (fun loop _fibre -> Luv.File.close ~loop fd)
 
     let ensure_closed t =
@@ -209,7 +209,7 @@ module Low_level = struct
     let to_luv = get "to_luv"
 
     let of_luv_no_hook fd =
-      { fd = `Open fd; release_hook = Eio.Hook.null }
+      { fd = `Open fd; release_hook = Eio.Switch.null_hook }
 
     let of_luv ~sw fd =
       let t = of_luv_no_hook fd in
@@ -250,7 +250,7 @@ module Low_level = struct
       | `Peek -> fd
       | `Take ->
         t.fd <- `Closed;
-        Eio.Hook.remove t.release_hook;
+        Eio.Switch.remove_hook t.release_hook;
         fd
   end
 

tests/test_lf_queue.md

@@ -41,24 +41,24 @@ val q : int Q.t = <abstr>
 # Q.close q;;
 - : unit = ()
 # Q.push q 2;;
-Exception: Eio_utils.Lf_queue.Closed.
+Exception: Eio_utils__Lf_queue.Closed.
 # Q.push_head q 3;;
 - : unit = ()
 # Q.pop q;;
 - : int option = Some 3
 # Q.pop q;;
 - : int option = Some 1
 # Q.pop q;;
-Exception: Eio_utils.Lf_queue.Closed.
+Exception: Eio_utils__Lf_queue.Closed.
 # Q.push_head q 4;;
-Exception: Eio_utils.Lf_queue.Closed.
+Exception: Eio_utils__Lf_queue.Closed.
 ```
 
 ## Closing an empty queue
 
 ```ocaml
 # let q = Q.create () in Q.close q; Q.push q 1;;
-Exception: Eio_utils.Lf_queue.Closed.
+Exception: Eio_utils__Lf_queue.Closed.
 ```
 
 ## Empty?
@@ -75,7 +75,7 @@ val q : int Q.t = <abstr>
 # Q.is_empty q;;
 - : bool = true
 # Q.close q; Q.is_empty q;;
-Exception: Eio_utils.Lf_queue.Closed.
+Exception: Eio_utils__Lf_queue.Closed.
 ```
 
 ## Pushing to the head