From 21fba9effa2c9a7822cc7c7119d8571648f063d8 Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Mon, 10 Nov 2014 12:17:59 +0100 Subject: [PATCH] more documentation in CCGen --- core/CCGen.mli | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/core/CCGen.mli b/core/CCGen.mli index c61670f6..fab98dc6 100644 --- a/core/CCGen.mli +++ b/core/CCGen.mli @@ -28,7 +28,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Values of type ['a Gen.t] represent a possibly infinite sequence of values of type 'a. One can only iterate once on the sequence, as it is consumed by iteration/deconstruction/access. [None] is returned when the generator -is exhausted. +is exhausted. Most functions consume elements. The submodule {!Restart} provides utilities to work with {b restartable generators}, that is, functions [unit -> 'a Gen.t] that @@ -78,25 +78,27 @@ module type S = sig (** {2 Basic combinators} *) val is_empty : _ t -> bool - (** Check whether the enum is empty. *) + (** Check whether the genertor is empty. Consumes one element if the + generator isn't empty. *) val fold : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b - (** Fold on the generator, tail-recursively *) + (** Fold on the generator, tail-recursively; consumes it *) val reduce : ('a -> 'a -> 'a) -> 'a t -> 'a - (** Fold on non-empty sequences (otherwise raise Invalid_argument) *) + (** Fold on non-empty sequences + @raise Invalid_argument if the generator is empty *) val scan : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b t (** Like {!fold}, but keeping successive values of the accumulator *) val iter : ('a -> unit) -> 'a t -> unit - (** Iterate on the enum *) + (** Iterate on the generator, consuming it *) val iteri : (int -> 'a -> unit) -> 'a t -> unit - (** Iterate on elements with their index in the enum, from 0 *) + (** Iterate on elements with their index in the enum, from 0. Consumes it. *) val length : _ t -> int - (** Length of an enum (linear time) *) + (** Length of a generator (linear time, consumes its input) *) val map : ('a -> 'b) -> 'a t -> 'b t (** Lazy map. No iteration is performed now, the function will be called @@ -217,7 +219,7 @@ module type S = sig [e1, e2, ... ] picks elements in [e1], [e2], in [e3], [e1], [e2] .... Once a generator is empty, it is skipped; when they are all empty, and none remains in the input, - their merge is also empty. + their merge is also empty. For instance, [merge [1;3;5] [2;4;6]] will be, in disorder, [1;2;3;4;5;6]. *) val intersection : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t -> 'a t