Revised docs for seq, unfold, from_loop in LazyList (#806)

seq: Revised basic description to fit first part of from_loop doc,
which seems clearer.  Also added note that you can create an infinite
list by passing a function that constantly returns true.

from_loop: Gave additional detail about what the next function
is supposed to do, and noted that its result pair might contain
different types.  Added a simple example where the types are
the same.  (This example could be done more simpy using seq.
I still don't understand the purpose of from_loop.)

I moved seq before from_loop because it's a more basic version of this
kind of operation.  from_loop is more specialized, and complicated,
but its name might suggest that it's the normal way of making a lazy
list by repeated application of a function.  Users should see seq
first before trying to work out what from_loop is for.

src/batLazyList.ml

@@ -74,14 +74,12 @@ let seq data next cond =
     else              Nil
   in lazy (aux data)
 
-
 let unfold (data:'b) (next: 'b -> ('a * 'b) option) =
   let rec aux data = match next data with
     | Some(a,b) -> Cons(a, lazy (aux b))
     | None      -> Nil
   in lazy (aux data)
 
-
 let from_loop (data:'b) (next:'b -> ('a * 'b)) : 'a t=
   let f' data =
     try  Some (next data)

src/batLazyList.mli

@@ -105,22 +105,39 @@ val from_while: (unit -> 'a option) -> 'a t
    results of [next].
    The list ends whenever [next] returns [None]. *)
 
-val from_loop: 'b -> ('b -> ('a * 'b)) -> 'a t
-(**[from_loop data next] creates a (possibly infinite) lazy list from
-   the successive results of applying [next] to [data], then to the
-   result, etc. The list ends whenever the function raises
-   {!LazyList.No_more_elements}.*)
-
 val seq: 'a -> ('a -> 'a) -> ('a -> bool) -> 'a t
-(** [seq init step cond] creates a sequence of data, which starts
-    from [init],  extends by [step],  until the condition [cond]
-    fails. E.g. [seq 1 ((+) 1) ((>) 100)] returns [[^1, 2, ... 99^]]. If [cond
-    init] is false, the result is empty. *)
+(**[seq data next cond] creates a lazy list from the successive results
+   of applying [next] to [data], then to the result, etc.  The list
+   continues until the condition [cond] fails.  For example, 
+   [seq 1 ((+) 1) ((>) 100)] returns [[^1, 2, ... 99^]].  If [cond init] 
+   is false, the result is empty.  To create an infinite lazy list, pass 
+   [(fun _ -> true)] as [cond]. *)
 
 val unfold: 'b -> ('b -> ('a * 'b) option) -> 'a t
 (**[unfold data next] creates a (possibly infinite) lazy list from
    the successive results of applying [next] to [data], then to the
-   result, etc. The list ends whenever the function returns [None]*)
+   result, etc. The list ends whenever [next] returns [None].  The function 
+   [next] should return a pair [option] whose first element will be the
+   current value of the sequence; the second element will be passed 
+   (lazily) to [next] in order to compute the following element.  One example
+   of a use of [unfold] is to make each element of the resulting sequence to 
+   depend on the previous two elements, as in this Fibonacci sequence 
+   definition:
+   {[
+     let data = (1, 1)
+     let next (x, y) = Some (x, (y, x + y))
+     let fib = unfold data next
+   ]}
+   The first element [x] of the pair within [Some] will be the current 
+   value of the sequence; the next value of the sequence, and the one after
+   that, are recorded as [y] and [x + y] respectively. *)
+
+val from_loop: 'b -> ('b -> ('a * 'b)) -> 'a t
+(**[from_loop data next] creates a (possibly infinite) lazy list from
+   the successive results of applying [next] to [data], then to the
+   result, etc.  The list ends whenever the function raises
+   {!LazyList.No_more_elements}.  (For further information see [unfold];
+   ignore references to [option] and [Some].) *)
 
 val init : int -> (int -> 'a) -> 'a t
 (** Similar to [Array.init], [init n f] returns the lazy list