From 5ad2b2df830f7cf24a8a9614059058916b71ebc7 Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Mon, 11 Nov 2013 23:30:48 +0100
Subject: [PATCH] doc

---
 gen.ml  |  7 ++++++-
 gen.mli | 15 +++++++++++----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/gen.ml b/gen.ml
index 494e8586..f418b294 100644
--- a/gen.ml
+++ b/gen.ml
@@ -860,6 +860,10 @@ let intersperse x gen =
 let product gena genb =
   let all_a = ref [] in
   let all_b = ref [] in
+  (* cur: current state, i.e., what we have to do next. Can be stop,
+    getLeft/getRight (to obtain next element from first/second generator),
+    or prodLeft/prodRIght to compute the product of an element with a list
+    of already met elements *)
   let cur = ref `GetLeft in
   let rec next () =
     match !cur with
@@ -937,7 +941,8 @@ let sort ?(cmp=Pervasives.compare) gen =
       then raise EOG
       else Heap.pop h
 
-(* FIXME: use a set *)
+(* NOTE: using a set is not really possible, because once we have built the
+  set there is no simple way to iterate on it *)
 let sort_uniq ?(cmp=Pervasives.compare) gen =
   uniq ~eq:(fun x y -> cmp x y = 0) (sort ~cmp gen)
 
diff --git a/gen.mli b/gen.mli
index f1447bab..0344af88 100644
--- a/gen.mli
+++ b/gen.mli
@@ -46,7 +46,11 @@ type 'a t = unit -> 'a
 
 type 'a gen = 'a t
 
-(** {2 Common signature for transient and restartable generators} *)
+(** {2 Common signature for transient and restartable generators}
+
+The signature {!S} abstracts on a type ['a t], where the [t] can be
+the type of transient or restartable generators. Some functions specify
+explicitely that they use ['a gen] (transient generators). *)
 
 module type S = sig
   type 'a t
@@ -312,6 +316,7 @@ val repeatedly : (unit -> 'a) -> 'a t
       if the function is a random generator). *)
 
 include S with type 'a t := 'a gen
+  (** Operations on {b transient} generators *)
 
 (** {2 Restartable generators} *)
 
@@ -333,8 +338,10 @@ end
 (** {2 Utils} *)
 
 val persistent : 'a t -> 'a Restart.t
-  (** Store content of the generator in memory, to be able to iterate on it
-      several times later *)
+  (** Store content of the transient generator in memory, to be able to iterate
+      on it several times later. If possible, consider using combinators
+      from {!Restart} directly instead. *)
 
 val start : 'a Restart.t -> 'a t
-  (** Create a new transient generator *)
+  (** Create a new transient generator.
+      [start gen] is the same as [gen ()] but is included for readability. *)