From 1f2bf2bb13a238e43046c8b8d26f284c31a47964 Mon Sep 17 00:00:00 2001
From: Gabriel Scherer <gabriel.scherer@gmail.com>
Date: Thu, 8 Feb 2024 15:47:35 +0100
Subject: [PATCH] MSeq and MRand documentation: give an example.

Suggested-by: Dai Weituo
---
 src/MRand.mli | 12 ++++++++++++
 src/MSeq.mli  | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/src/MRand.mli b/src/MRand.mli
index ef1cc7f..cffecc8 100644
--- a/src/MRand.mli
+++ b/src/MRand.mli
@@ -1 +1,13 @@
 include Utils.MonadPlus
+
+(**
+   We demand that [MRand.run e] returns an infinite sequence of solutions
+   sampled from [e], for example
+   {[
+     (let open MRand in sum [return 1; return 2; return 3])
+     |> MRand.run     (* infinite stream of random samples *)
+     |> Seq.take 10   (* take the first 10 elements *)
+     |> List.of_seq
+   ]}
+   could be the list [[1; 2; 1; 2; 1; 1; 1; 3; 3; 2]].
+*)
diff --git a/src/MSeq.mli b/src/MSeq.mli
index ef1cc7f..bfa8aaa 100644
--- a/src/MSeq.mli
+++ b/src/MSeq.mli
@@ -1 +1,13 @@
 include Utils.MonadPlus
+
+(**
+   We demand that [MSeq.run e] returns the finite list of solutions
+   for [e], for example
+   {[
+     (let open MSeq in sum [return 1; return 2; return 3])
+     |> MSeq.run    (* list of all solutions *)
+     |> List.of_seq
+   ]}
+   should be the list [[1; 2; 3]] -- or maybe the same elements in
+   some other order.
+*)