A bit more documentation improvement.

src/bounded_queue/bounded_queue_intf.mli

@@ -109,7 +109,9 @@ module type BOUNDED_QUEUE = sig
       queue is full. *)
 end
 
-(** {1 Examples}
+(** {1 Examples} *)
+
+(** {2 Sequential example}
     An example top-level session:
     {[
       # open Saturn.Bounded_queue
@@ -137,8 +139,15 @@ end
       - : int option = None
       # pop_exn t
       Exception: Saturn__Bounded_queue.Empty.]}
+*)
+
+(** {2 Multicore example}
+
+  **Note** that the use of a barrier is only necessary to make the result of 
+  this example interesting by improving the likelihood of parallelism. 
+  Spawning a domain is a costly operation compared to the work actually run on them
+  here. In practice, you should not use a barrier.
 
-    A multicore example: 
     {@ocaml non-deterministic[
       # open Saturn.Bounded_queue
       # let t :int t = create ~capacity:4 ()

src/bounded_stack.mli

@@ -167,7 +167,9 @@ the [seq] is too long to fit in the stack.
 
 🐌 This is a linear-time operation. *)
 
-(** {1 Examples}
+(** {1 Examples} *)
+
+(** {2 Sequential example}
     An example top-level session:
     {[
       # open Saturn.Bounded_stack
@@ -187,8 +189,15 @@ the [seq] is too long to fit in the stack.
       - : int option = None
       # pop_exn t
       Exception: Saturn__Bounded_stack.Empty.]}
+*)
+
+(** {2 Multicore example}
+
+  **Note** that the use of a barrier is only necessary to make the result of 
+  this example interesting by improving the likelihood of parallelism. 
+  Spawning a domain is a costly operation compared to the work actually run on them
+  here. In practice, you should not use a barrier.
 
-    A multicore example: 
     {@ocaml non-deterministic[
       # open Saturn.Bounded_stack
       # let t :int t = create ()
@@ -219,5 +228,4 @@ the [seq] is too long to fit in the stack.
       # Domain.join domain_popper
       - : int option list = [Some 42; Some 3; Some 2; Some 1; None; Some 12]
       ]}
- 
     *)

src/treiber_stack.mli

@@ -108,7 +108,9 @@ val add_seq : 'a t -> 'a Seq.t -> unit
 
   🐌 This is a linear-time operation on the size of [elements]. *)
 
-(** {1 Examples}
+(** {1 Examples} *)
+
+(** {2 Sequential example}
   An example top-level session:
   {[
     # open Saturn.Stack
@@ -126,8 +128,15 @@ val add_seq : 'a t -> 'a Seq.t -> unit
     - : int list = [2; 1; 42]
     # pop_exn t
     Exception: Saturn__Treiber_stack.Empty.]}
+*)
+
+(** {2 Multicore example}
+
+**Note** that the use of a barrier is only necessary to make the result of 
+  this example interesting by improving the likelihood of parallelism. 
+  Spawning a domain is a costly operation compared to the work actually run on them
+  here. In practice, you should not use a barrier.
 
-  A multicore example: 
   {@ocaml non-deterministic[
     # open Saturn.Stack
     # let t : int t = create ()
@@ -158,5 +167,4 @@ val add_seq : 'a t -> 'a Seq.t -> unit
     # Domain.join domain_popper
     - : int option list = [Some 42; Some 3; Some 2; Some 1; None; Some 12]
     ]}
- 
   *)