Improving comments presentation

src/core/CCArray.mli

@@ -16,19 +16,20 @@ type 'a printer = Format.formatter -> 'a -> unit
 include module type of struct include Array end
 
 type 'a t = 'a array
+(** The type for arrays *)
 
 val empty : 'a t
-(** The empty array, physically equal to [||]. *)
+(** [empty] is the empty array, physically equal to [||]. *)
 
 val equal : 'a equal -> 'a t equal
-(** Hoist an equality test for elements to arrays.
+(** [equal eq a1 a2] is [true] if the lengths of [a1] and [a2] are the same
-    Arrays are only equal if their lengths are the same and
+    and if their corresponding elements test equal, using [eq]. *)
-    corresponding elements test equal. *)
 
 val compare : 'a ord -> 'a t ord
+(** [compare cmp a1 a2] compares arrays [a1] and [a2] using the function comparison [cmp]. *)
 
 val swap : 'a t -> int -> int -> unit
-(** [swap arr i j] swaps elements at indices [i] and [j].
+(** [swap a i j] swaps elements at indices [i] and [j].
     @since 1.4 *)
 
 val get : 'a t -> int -> 'a
@@ -53,18 +54,19 @@ val set : 'a t -> int -> 'a -> unit
     if [n] is outside the range 0 to [length a - 1]. *)
 
 val length : _ t -> int
-(** Return the length (number of elements) of the given array. *)
+(** [length a] returns the length (number of elements) of the given array [a]. *)
 
 val fold : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a
-(** [fold f x a] computes [f (... (f (f x a.(0)) a.(1)) ...) a.(n-1)],
+(** [fold f acc a] computes [f (... (f (f acc a.(0)) a.(1)) ...) a.(n-1)],
     where [n] is the length of the array [a]. *)
 
 val foldi : ('a -> int -> 'b -> 'a) -> 'a -> 'b t -> 'a
-(** Fold left on array, with index. *)
+(** [foldi f acc a] is just like {!fold}, but it also passes in the index
+    of each element as the second argument to the folded function [f]. *)
 
 val fold_while : ('a -> 'b -> 'a * [`Stop | `Continue]) -> 'a -> 'b t -> 'a
-(** Fold left on array until a stop condition via [('a, `Stop)] is
+(** [fold_while f acc a] folds left on array [a] until a stop condition via [('a, `Stop)]
-    indicated by the accumulator.
+    is indicated by the accumulator.
     @since 0.8 *)
 
 val fold_map : ('acc -> 'a -> 'acc * 'b) -> 'acc -> 'a t -> 'acc * 'b t
@@ -79,27 +81,26 @@ val scan_left : ('acc -> 'a -> 'acc) -> 'acc -> 'a t -> 'acc t
     @since 1.2 *)
 
 val iter : ('a -> unit) -> 'a t -> unit
-(** [iter f a] applies function [f] in turn to all
+(** [iter f a] applies function [f] in turn to all elements of [a].
-    the elements of [a].  It is equivalent to
+    It is equivalent to [f a.(0); f a.(1); ...; f a.(length a - 1); ()]. *)
-    [f a.(0); f a.(1); ...; f a.(length a - 1); ()]. *)
 
 val iteri : (int -> 'a -> unit) -> 'a t -> unit
-(** Like {!Array.iter}, but the function is applied to the index of the
+(** [iteri f a] is like {!iter}, but the function [f] is applied with the index of the
     element as first argument, and the element itself as second argument. *)
 
 val blit : 'a t -> int -> 'a t -> int -> int -> unit
-(** [blit v1 o1 v2 o2 len] copies [len] elements
+(** [blit a1 o1 a2 o2 len] copies [len] elements
-    from array [v1], starting at element number [o1], to array [v2],
+    from array [a1], starting at element number [o1], to array [a2],
     starting at element number [o2]. It works correctly even if
-    [v1] and [v2] are the same array, and the source and
+    [a1] and [a2] are the same array, and the source and
     destination chunks overlap.
 
-    Raise [Invalid_argument "Array.blit"] if [o1] and [len] do not
+    Raise [Invalid_argument "CCArray.blit"] if [o1] and [len] do not
-    designate a valid subarray of [v1], or if [o2] and [len] do not
+    designate a valid subarray of [a1], or if [o2] and [len] do not
-    designate a valid subarray of [v2]. *)
+    designate a valid subarray of [a2]. *)
 
 val reverse_in_place : 'a t -> unit
-(** Reverse the array in place. *)
+(** [reverse_in_place a] reverses the array [a] in place. *)
 
 val sorted : ('a -> 'a -> int) -> 'a t -> 'a array
 (** [sorted cmp a] makes a copy of [a] and sorts it with [cmp].
@@ -128,163 +129,183 @@ val sort_ranking : ('a -> 'a -> int) -> 'a t -> int array
 
 val find_map : ('a -> 'b option) -> 'a t -> 'b option
 (** [find_map f a] returns [Some y] if there is an element [x] such
-    that [f x = Some y], else it returns [None].
+    that [f x = Some y]. Otherwise returns [None].
     @since 1.3 *)
 
 val find : ('a -> 'b option) -> 'a t -> 'b option
-(** Alias to {!find_map}.
+(** [find f a] is an alias to {!find_map}.
     @deprecated since 1.3, use {!find_map} instead. *)
 
 val find_map_i : (int -> 'a -> 'b option) -> 'a t -> 'b option
-(** Like {!find_map}, but also pass the index to the predicate function.
+(** [find_map_i f a] is like {!find_map}, but the index of the element is also passed
+    to the predicate function [f].
     @since 1.3 *)
 
 val findi : (int -> 'a -> 'b option) -> 'a t -> 'b option
-(** Alias to {!find_map_i}.
+(** [findi f a] is an alias to {!find_map_i}.
     @since 0.3.4
     @deprecated since 1.3, use {!find_map_i} instead. *)
 
 val find_idx : ('a -> bool) -> 'a t -> (int * 'a) option
-(** [find_idx p x] returns [Some (i,x)] where [x] is the [i]-th element of [l],
+(** [find_idx p a] returns [Some (i,x)] where [x] is the [i]-th element of [a],
     and [p x] holds. Otherwise returns [None].
     @since 0.3.4 *)
 
 val lookup : cmp:'a ord -> 'a -> 'a t -> int option
-(** Lookup the index of some value in a sorted array.
+(** [lookup cmp x a] lookups the index of some key [x] in a sorted array [a].
-    Undefined behavior if the array is not sorted wrt [cmp].
+    Undefined behavior if the array [a] is not sorted wrt [cmp].
     Complexity: [O(log (n))] (dichotomic search).
-    @return [None] if the key is not present, or
+    @return [None] if the key [x] is not present, or
       [Some i] ([i] the index of the key) otherwise. *)
 
 val lookup_exn : cmp:'a ord -> 'a -> 'a t -> int
-(** Like {!lookup}, but
+(** [lookup_exn cmp x a] is like {!lookup}, but
-    @raise Not_found if the key is not present. *)
+    @raise Not_found if the key [x] is not present. *)
 
 val bsearch : cmp:('a -> 'a -> int) -> 'a -> 'a t ->
   [ `All_lower | `All_bigger | `Just_after of int | `Empty | `At of int ]
-(** [bsearch ?cmp x arr] finds the index of the object [x] in the array [arr],
+(** [bsearch ~cmp x a] finds the index of the object [x] in the array [a],
-    provided [arr] is {b sorted} using [cmp]. If the array is not sorted,
+    provided [a] is {b sorted} using [cmp]. If the array is not sorted,
-    the result is not specified.
+    the result is not specified (may raise Invalid_argument).
 
-    Complexity: [O(log n)] where n is the length of the array
+    Complexity: [O(log n)] where n is the length of the array [a]
     (dichotomic search).
 
     @return
-    - [`At i] if [cmp arr.(i) x = 0] (for some i).
+    - [`At i] if [cmp a.(i) x = 0] (for some i).
-    - [`All_lower] if all elements of [arr] are lower than [x].
+    - [`All_lower] if all elements of [a] are lower than [x].
-    - [`All_bigger] if all elements of [arr] are bigger than [x].
+    - [`All_bigger] if all elements of [a] are bigger than [x].
-    - [`Just_after i] if [arr.(i) < x < arr.(i+1)].
+    - [`Just_after i] if [a.(i) < x < a.(i+1)].
-    - [`Empty] if the array is empty.
+    - [`Empty] if the array [a] is empty.
 
     @raise Invalid_argument if the array is found to be unsorted w.r.t [cmp].
     @since 0.13 *)
 
 val for_all : ('a -> bool) -> 'a t -> bool
-(** [for_all p [|a1; ...; an|]] checks if all elements of the array
+(** [for_all p [|a1; ...; an|]] is [true] if all elements of the array
     satisfy the predicate [p]. That is, it returns
     [(p a1) && (p a2) && ... && (p an)]. *)
 
 val for_all2 : ('a -> 'b -> bool) -> 'a t -> 'b t -> bool
-(** Forall on pairs of arrays.
+(** [for_all2 p [|a1; ...; an|] [|b1; ...; bn|]] is [true] if each pair of elements [ai bi]
-    @raise Invalid_argument if they have distinct lengths.
+    satisfies the predicate [p].
+    That is, it returns [(p a1 b1) && (p a2 b2) && ... && (p an bn)].
+
+    @raise Invalid_argument if arrays have distinct lengths.
     Allow different types.
     @since 0.20 *)
 
 val exists : ('a -> bool) -> 'a t -> bool
-(** [exists p [|a1; ...; an|]] checks if at least one element of
+(** [exists p [|a1; ...; an|]] is [true] if at least one element of
     the array satisfies the predicate [p]. That is, it returns
     [(p a1) || (p a2) || ... || (p an)]. *)
 
 val exists2 : ('a -> 'b -> bool) -> 'a t -> 'b t -> bool
-(** Exists on pairs of arrays.
+(** [exists2 p [|a1; ...; an|] [|b1; ...; bn|]] is [true] if any pair of elements [ai bi]
-    @raise Invalid_argument if they have distinct lengths.
+    satisfies the predicate [p].
+    That is, it returns [(p a1 b1) || (p a2 b2) || ... || (p an bn)].
+
+    @raise Invalid_argument if arrays have distinct lengths.
     Allow different types.
     @since 0.20 *)
 
 val fold2 : ('acc -> 'a -> 'b -> 'acc) -> 'acc -> 'a t -> 'b t -> 'acc
-(** Fold on two arrays stepwise.
+(** [fold2 f acc a b] fold on two arrays [a] and [b] stepwise.
-    @raise Invalid_argument if they have distinct lengths.
+    It computes [f (... (f acc a1 b1)...) an bn].
+
+    @raise Invalid_argument if arrays have distinct lengths.
     @since 0.20 *)
 
 val iter2 : ('a -> 'b -> unit) -> 'a t -> 'b t -> unit
-(** Iterate on two arrays stepwise.
+(** [iter2 f a b] iterates on the two arrays [a] and [b] stepwise.
-    @raise Invalid_argument if they have distinct lengths.
+    It is equivalent to  [f a0 b0; ...; f a.(length a - 1) b.(length b - 1); ()].
+
+    @raise Invalid_argument if arrays have distinct lengths.
     @since 0.20 *)
 
 val shuffle : 'a t -> unit
-(** Shuffle randomly the array, in place. *)
+(** [shuffle a] randomly shuffles the array [a], in place. *)
 
 val shuffle_with : Random.State.t -> 'a t -> unit
-(** Like {!shuffle} but using a specialized random state. *)
+(** [shuffle_with rs a] randomly shuffles the array [a] (like {!shuffle}) but a specialized random
+    state [rs] is used to control the random numbers being produced during shuffling (for reproducibility). *)
 
 val random_choose : 'a t -> 'a random_gen
-(** Choose an element randomly.
+(** [random_choose a rs] randomly chooses an element of [a].
     @raise Not_found if the array/slice is empty. *)
 
 val to_seq : 'a t -> 'a sequence
-(** Return a [sequence] of the elements of an array.
+(** [to_seq a] returns a [sequence] of the elements of an array [a].
-    The input array is shared with the sequence and modifications of it will result
+    The input array [a] is shared with the sequence and modification of it will result
     in modification of the sequence. *)
 
 val to_gen : 'a t -> 'a gen
-(** Return a [gen] of the elements of an array. *)
+(** [to_gen a] returns a [gen] of the elements of an array [a]. *)
 
 val to_klist : 'a t -> 'a klist
-(** Return a [klist] of the elements of an array. *)
+(** [to_klist] returns a [klist] of the elements of an array [a]. *)
 
 (** {2 IO} *)
 
 val pp: ?sep:string -> 'a printer -> 'a t printer
-(** Print an array of items with printing function. *)
+(** [pp ~sep pp_item ppf a] formats the array [a] on [ppf].
+    Each element is formatted with [pp_item] and elements are separated
+    by [sep] (defaults to ", "). *)
 
 val pp_i: ?sep:string -> (int -> 'a printer) -> 'a t printer
-(** Print an array, giving the printing function both index and item. *)
+(** [pp_i ~sep pp_item ppf a] prints the array [a] on [ppf].
+    The printing function [pp_item] is giving both index and element.
+    Elements are separated by [sep] (defaults to ", "). *)
 
 val map : ('a -> 'b) -> 'a t -> 'b t
-(** [map f a] applies function [f] to all the elements of [a],
+(** [map f a] applies function [f] to all elements of [a],
     and builds an array with the results returned by [f]:
     [[| f a.(0); f a.(1); ...; f a.(length a - 1) |]]. *)
 
 val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
-(** [map2 f a b] applies function [f] to all the elements of [a] and [b],
+(** [map2 f a b] applies function [f] to all elements of [a] and [b],
     and builds an array with the results returned by [f]:
     [[| f a.(0) b.(0); ...; f a.(length a - 1) b.(length b - 1)|]].
-      @raise Invalid_argument if they have distinct lengths.
+
-      @since 0.20 *)
+    @raise Invalid_argument if [a] and [b] have distinct lengths.
+    @since 0.20 *)
 
 val rev : 'a t -> 'a t
-(** Copy + reverse in place.
+(** [rev a] copies the array [a] and reverses it in place.
     @since 0.20 *)
 
 val filter : ('a -> bool) -> 'a t -> 'a t
-(** Filter elements out of the array. Only the elements satisfying
+(** [filter p a] filters elements out of the array [a]. Only the elements satisfying
-    the given predicate will be kept. *)
+    the given predicate [p] will be kept. *)
 
 val filter_map : ('a -> 'b option) -> 'a t -> 'b t
-(** Map each element into another value, or discard it. *)
+(** [filter_map f [|a1; ...; an|]] calls [(f a1) ... (f an)] and returns an array [b] consisting
+    of all elements [bi] such as [f ai = Some bi]. When [f] returns [None], the corresponding
+    element of [a] is discarded. *)
 
 val flat_map : ('a -> 'b t) -> 'a t -> 'b array
-(** Transform each element into an array, then flatten. *)
+(** [flat_map f a] transforms each element of [a] into an array, then flattens. *)
 
 val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
-(** Infix version of {!flat_map}. *)
+(** [a >>= f] is the infix version of {!flat_map}. *)
 
 val (>>|) : 'a t -> ('a -> 'b) -> 'b t
-(** Infix version of {!map}.
+(** [a >>| f] is the infix version of {!map}.
     @since 0.8 *)
 
 val (>|=) : 'a t -> ('a -> 'b) -> 'b t
-(** Infix version of {!map}.
+(** [a >|= f] is the infix version of {!map}.
     @since 0.8 *)
 
 val except_idx : 'a t -> int -> 'a list
-(** Remove given index, obtaining the list of the other elements. *)
+(** [except_idx a i] removes the element of [a] at given index [i], and returns
+    the list of the other elements. *)
 
 val (--) : int -> int -> int t
-(** Range array. Bounds included. *)
+(** [x -- y] creates an array containing integers in the range [x .. y]. Bounds included. *)
 
 val (--^) : int -> int -> int t
-(** Range array, excluding right bound.
+(** [x --^ y] creates an array containing integers in the range [x .. y]. Right bound excluded.
     @since 0.17 *)
 
 val random : 'a random_gen -> 'a t random_gen
@@ -307,6 +328,6 @@ end
 val sort_generic :
   (module MONO_ARRAY with type t = 'arr and type elt = 'elt) ->
   cmp:('elt -> 'elt -> int) -> 'arr -> unit
-(** Sort the array, without allocating (eats stack space though). Performance
+(** [sort_generic (module M) cmp a] sorts the array [a], without allocating (eats stack space though).
-    might be lower than {!Array.sort}.
+    Performance might be lower than {!Array.sort}.
     @since 0.14 *)

src/core/CCArrayLabels.mli

@@ -1,4 +1,3 @@
-
 (* This file is free software, part of containers. See file "license" for more details. *)
 
 (** {1 Array utils} *)
@@ -20,19 +19,20 @@ external make_float : int -> float array = "caml_make_float_vect" (* compat *)
 include module type of struct include ArrayLabels end
 
 type 'a t = 'a array
+(** The type for arrays *)
 
 val empty : 'a t
-(** The empty array, physically equal to [||]. *)
+(** [empty] is the empty array, physically equal to [||]. *)
 
 val equal : 'a equal -> 'a t equal
-(** Hoist an equality test for elements to arrays.
+(** [equal eq a1 a2] is [true] if the lengths of [a1] and [a2] are the same
-    Arrays are only equal if their lengths are the same and
+    and if their corresponding elements test equal, using [eq]. *)
-    corresponding elements test equal. *)
 
 val compare : 'a ord -> 'a t ord
+(** [compare cmp a1 a2] compares arrays [a1] and [a2] using the function comparison [cmp]. *)
 
 val swap : 'a t -> int -> int -> unit
-(** [swap arr i j] swaps elements at indices [i] and [j].
+(** [swap a i j] swaps elements at indices [i] and [j].
     @since 1.4 *)
 
 val get : 'a t -> int -> 'a
@@ -57,74 +57,73 @@ val set : 'a t -> int -> 'a -> unit
     if [n] is outside the range 0 to [length a - 1]. *)
 
 val length : _ t -> int
-(** Return the length (number of elements) of the given array. *)
+(** [length a] returns the length (number of elements) of the given array [a]. *)
 
 val fold : f:('a -> 'b -> 'a) -> init:'a -> 'b t -> 'a
-(** [fold f x a] computes [f (... (f (f x a.(0)) a.(1)) ...) a.(n-1)],
+(** [fold ~f ~init a] computes [~f (... (~f (~f ~init a.(0)) a.(1)) ...) a.(n-1)],
     where [n] is the length of the array [a]. *)
 
 val foldi : f:('a -> int -> 'b -> 'a) -> init:'a -> 'b t -> 'a
-(** Fold left on array, with index. *)
+(** [foldi ~f ~init a] is just like {!fold}, but it also passes in the index
+    of each element as the second argument to the folded function [~f]. *)
 
 val fold_while : f:('a -> 'b -> 'a * [`Stop | `Continue]) -> init:'a -> 'b t -> 'a
-(** Fold left on array until a stop condition via [('a, `Stop)] is
+(** [fold_while ~f ~init a] folds left on array [a] until a stop condition via [('a, `Stop)]
-    indicated by the accumulator.
+    is indicated by the accumulator.
     @since 0.8 *)
 
 val fold_map : f:('acc -> 'a -> 'acc * 'b) -> init:'acc -> 'a t -> 'acc * 'b t
-(** [fold_map f acc a] is a [fold_left]-like function, but it also maps the
+(** [fold_map ~f ~init a] is a [fold_left]-like function, but it also maps the
     array to another array.
     @since 2.1 *)
 
 val scan_left : f:('acc -> 'a -> 'acc) -> init:'acc -> 'a t -> 'acc t
-(** [scan_left f acc a] returns the array
+(** [scan_left ~f ~init a] returns the array
-    [ [|acc; f acc x0; f (f acc a.(0)) a.(1); …|] ].
+    [ [|~init; ~f ~init x0; ~f (~f ~init a.(0)) a.(1); …|] ].
 
     @since 2.1 *)
     
-
 val iter : f:('a -> unit) -> 'a t -> unit
-(** [iter f a] applies function [f] in turn to all
+(** [iter ~f a] applies function [~f] in turn to all elements of [a].  
-    the elements of [a].  It is equivalent to
+    It is equivalent to [~f a.(0); ~f a.(1); ...; ~f a.(length a - 1); ()]. *)
-    [f a.(0); f a.(1); ...; f a.(length a - 1); ()]. *)
 
 val iteri : f:(int -> 'a -> unit) -> 'a t -> unit
-(** Like {!Array.iter}, but the function is applied to the index of the
+(** [iteri ~f a] is like {!iter}, but the function [~f] is applied with the index of the
     element as first argument, and the element itself as second argument. *)
   
 val blit : 'a t -> int -> 'a t -> int -> int -> unit
-(** [blit v1 o1 v2 o2 len] copies [len] elements
+(** [blit a1 o1 a2 o2 len] copies [len] elements
-    from array [v1], starting at element number [o1], to array [v2],
+    from array [a1], starting at element number [o1], to array [a2],
     starting at element number [o2]. It works correctly even if
-    [v1] and [v2] are the same array, and the source and
+    [a1] and [a2] are the same array, and the source and
     destination chunks overlap.
 
-    Raise [Invalid_argument "Array.blit"] if [o1] and [len] do not
+    Raise [Invalid_argument "CCArray.blit"] if [o1] and [len] do not
-    designate a valid subarray of [v1], or if [o2] and [len] do not
+    designate a valid subarray of [a1], or if [o2] and [len] do not
-    designate a valid subarray of [v2]. *)
+    designate a valid subarray of [a2]. *)
 
 val reverse_in_place : 'a t -> unit
-(** Reverse the array in place. *)
+(** [reverse_in_place a] reverses the array [a] in place. *)
 
 val sorted : f:('a -> 'a -> int) -> 'a t -> 'a array
-(** [sorted cmp a] makes a copy of [a] and sorts it with [cmp].
+(** [sorted ~f a] makes a copy of [a] and sorts it with [~f].
     @since 1.0 *)
 
 val sort_indices : f:('a -> 'a -> int) -> 'a t -> int array
-(** [sort_indices cmp a] returns a new array [b], with the same length as [a],
+(** [sort_indices ~f a] returns a new array [b], with the same length as [a],
-    such that [b.(i)] is the index at which the [i]-th element of [sorted cmp a]
+    such that [b.(i)] is the index at which the [i]-th element of [sorted ~f a]
     appears in [a]. [a] is not modified.
 
-    In other words, [map (fun i -> a.(i)) (sort_indices cmp a) = sorted cmp a].
+    In other words, [map (fun i -> a.(i)) (sort_indices ~f a) = sorted ~f a].
     [sort_indices] yields the inverse permutation of {!sort_ranking}.
     @since 1.0 *)
 
 val sort_ranking : f:('a -> 'a -> int) -> 'a t -> int array
-(** [sort_ranking cmp a] returns a new array [b], with the same length as [a],
+(** [sort_ranking ~f a] returns a new array [b], with the same length as [a],
     such that [b.(i)] is the index at which the [i]-th element of [a] appears
-    in [sorted cmp a]. [a] is not modified.
+    in [sorted ~f a]. [a] is not modified.
 
-    In other words, [map (fun i -> (sorted cmp a).(i)) (sort_ranking cmp a) = a].
+    In other words, [map (fun i -> (sorted ~f a).(i)) (sort_ranking ~f a) = a].
     [sort_ranking] yields the inverse permutation of {!sort_indices}.
 
     In the absence of duplicate elements in [a], we also have
@@ -132,163 +131,184 @@ val sort_ranking : f:('a -> 'a -> int) -> 'a t -> int array
     @since 1.0 *)
 
 val find_map : f:('a -> 'b option) -> 'a t -> 'b option
-(** [find_map f a] returns [Some y] if there is an element [x] such
+(** [find_map ~f a] returns [Some y] if there is an element [x] such
-    that [f x = Some y], else it returns [None].
+    that [~f x = Some y]. Otherwise returns [None].
     @since 2.1 *)
 
 val find : f:('a -> 'b option) -> 'a t -> 'b option
-(** [find f a] returns [Some y] if there is an element [x] such
+(** [find ~f a] is an alias to {!find_map}.
-    that [f x = Some y], else it returns [None].
     @deprecated since 2.1, use {!find_map} instead. *)
 
 val find_map_i : f:(int -> 'a -> 'b option) -> 'a t -> 'b option
-(** Like {!find_map}, but also pass the index to the predicate function.
+(** [find_map_i ~f a] is like {!find_map}, but the index of the element is also passed
+    to the predicate function [~f].
     @since 2.1 *)
 
 val findi : f:(int -> 'a -> 'b option) -> 'a t -> 'b option
-(** Like {!find}, but also pass the index to the predicate function.
+(** [findi ~f a] is an alias to {!find_map_i}.
     @since 0.3.4
     @deprecated since 2.1, use {!find_map_i} instead. *)
 
 val find_idx : f:('a -> bool) -> 'a t -> (int * 'a) option
-(** [find_idx p x] returns [Some (i,x)] where [x] is the [i]-th element of [l],
+(** [find_idx ~f a] returns [Some (i,x)] where [x] is the [i]-th element of [a],
-    and [p x] holds. Otherwise returns [None].
+    and [~f x] holds. Otherwise returns [None].
     @since 0.3.4 *)
 
 val lookup : cmp:'a ord -> key:'a -> 'a t -> int option
-(** Lookup the index of some value in a sorted array.
+(** [lookup ~cmp ~key a] lookups the index of some key [~key] in a sorted array [a].
-    Undefined behavior if the array is not sorted wrt [cmp].
+    Undefined behavior if the array [a] is not sorted wrt [~cmp].
     Complexity: [O(log (n))] (dichotomic search).
-    @return [None] if the key is not present, or
+    @return [None] if the key [~key] is not present, or
       [Some i] ([i] the index of the key) otherwise. *)
 
 val lookup_exn : cmp:'a ord -> key:'a -> 'a t -> int
-(** Like {!lookup}, but
+(** [lookup_exn ~cmp ~key a] is like {!lookup}, but
-    @raise Not_found if the key is not present. *)
+    @raise Not_found if the key [~key] is not present. *)
 
 val bsearch : cmp:('a -> 'a -> int) -> key:'a -> 'a t ->
   [ `All_lower | `All_bigger | `Just_after of int | `Empty | `At of int ]
-(** [bsearch ?cmp key arr] finds the index of the object [key] in the array [arr],
+(** [bsearch ~cmp ~key a] finds the index of the object [~key] in the array [a],
-    provided [arr] is {b sorted} using [cmp]. If the array is not sorted,
+    provided [a] is {b sorted} using [~cmp]. If the array is not sorted,
     the result is not specified (may raise Invalid_argument).
 
-    Complexity: [O(log n)] where n is the length of the array
+    Complexity: [O(log n)] where n is the length of the array [a]
     (dichotomic search).
 
     @return
-    - [`At i] if [cmp arr.(i) key = 0] (for some i).
+    - [`At i] if [cmp a.(i) key = 0] (for some i).
-    - [`All_lower] if all elements of [arr] are lower than [key].
+    - [`All_lower] if all elements of [a] are lower than [key].
-    - [`All_bigger] if all elements of [arr] are bigger than [key].
+    - [`All_bigger] if all elements of [a] are bigger than [key].
-    - [`Just_after i] if [arr.(i) < key < arr.(i+1)].
+    - [`Just_after i] if [a.(i) < key < a.(i+1)].
-    - [`Empty] if the array is empty.
+    - [`Empty] if the array [a] is empty.
 
     @raise Invalid_argument if the array is found to be unsorted w.r.t [cmp].
     @since 0.13 *)
 
 val for_all : f:('a -> bool) -> 'a t -> bool
-(** [for_all p [|a1; ...; an|]] checks if all elements of the array
+(** [for_all ~f [|a1; ...; an|]] is [true] if all elements of the array
-    satisfy the predicate [p]. That is, it returns
+    satisfy the predicate [~f]. That is, it returns
-    [(p a1) && (p a2) && ... && (p an)]. *)
+    [(~f a1) && (~f a2) && ... && (~f an)]. *)
 
 val for_all2 : f:('a -> 'b -> bool) -> 'a t -> 'b t -> bool
-(** Forall on pairs of arrays.
+(** [for_all2 ~f [|a1; ...; an|] [|b1; ...; bn|]] is [true] if each pair of elements [ai bi]
-    @raise Invalid_argument if they have distinct lengths.
+    satisfies the predicate [~f].
+    That is, it returns [(~f a1 b1) && (~f a2 b2) && ... && (~f an bn)].
+
+    @raise Invalid_argument if arrays have distinct lengths.
     Allow different types.
     @since 0.20 *)
 
 val exists : f:('a -> bool) -> 'a t -> bool
-(** [exists p [|a1; ...; an|]] checks if at least one element of
+(** [exists ~f [|a1; ...; an|]] is [true] if at least one element of
-    the array satisfies the predicate [p]. That is, it returns
+    the array satisfies the predicate [~f]. That is, it returns
-    [(p a1) || (p a2) || ... || (p an)]. *)
+    [(~f a1) || (~f a2) || ... || (~f an)]. *)
 
 val exists2 : f:('a -> 'b -> bool) -> 'a t -> 'b t -> bool
-(** Exists on pairs of arrays.
+(** [exists2 ~f [|a1; ...; an|] [|b1; ...; bn|]] is [true] if any pair of elements [ai bi]
-    @raise Invalid_argument if they have distinct lengths.
+    satisfies the predicate [~f].
+    That is, it returns [(~f a1 b1) || (~f a2 b2) || ... || (~f an bn)].
+
+    @raise Invalid_argument if arrays have distinct lengths.
     Allow different types.
     @since 0.20 *)
 
 val fold2 : f:('acc -> 'a -> 'b -> 'acc) -> init:'acc -> 'a t -> 'b t -> 'acc
-(** Fold on two arrays stepwise.
+(** [fold2 ~f ~init a b] fold on two arrays [a] and [b] stepwise.
-    @raise Invalid_argument if they have distinct lengths.
+    It computes [~f (... (~f ~init a1 b1)...) an bn].
+
+    @raise Invalid_argument if [a] and [b] have distinct lengths.
     @since 0.20 *)
 
 val iter2 : f:('a -> 'b -> unit) -> 'a t -> 'b t -> unit
-(** Iterate on two arrays stepwise.
+(** [iter2 ~f a b] iterates on the two arrays [a] and [b] stepwise.
-    @raise Invalid_argument if they have distinct lengths.
+    It is equivalent to  [~f a0 b0; ...; ~f a.(length a - 1) b.(length b - 1); ()].
+
+    @raise Invalid_argument if [a] and [b] have distinct lengths.
     @since 0.20 *)
 
 val shuffle : 'a t -> unit
-(** Shuffle randomly the array, in place. *)
+(** [shuffle a] randomly shuffles the array [a], in place. *)
 
 val shuffle_with : Random.State.t -> 'a t -> unit
-(** Like {!shuffle} but using a specialized random state. *)
+(** [shuffle_with rs a] randomly shuffles the array [a] (like {!shuffle}) but a specialized random
+    state [rs] is used to control the random numbers being produced during shuffling (for reproducibility). *)
 
 val random_choose : 'a t -> 'a random_gen
-(** Choose an element randomly.
+(** [random_choose a rs] randomly chooses an element of [a].
     @raise Not_found if the array/slice is empty. *)
 
 val to_seq : 'a t -> 'a sequence
-(** Return a [sequence] of the elements of an array. *)
+(** [to_seq a] returns a [sequence] of the elements of an array [a].
+    The input array [a] is shared with the sequence and modification of it will result
+    in modification of the sequence. *)
 
 val to_gen : 'a t -> 'a gen
-(** Return a [gen] of the elements of an array. *)
+(** [to_gen a] returns a [gen] of the elements of an array [a]. *)
 
 val to_klist : 'a t -> 'a klist
-(** Return a [klist] of the elements of an array. *)
+(** [to_klist] returns a [klist] of the elements of an array [a]. *)
 
 (** {2 IO} *)
 
 val pp: ?sep:string -> 'a printer -> 'a t printer
-(** Print an array of items with printing function. *)
+(** [pp ~sep pp_item ppf a] formats the array [a] on [ppf].
+    Each element is formatted with [pp_item] and elements are separated
+    by [sep] (defaults to ", "). *)
 
 val pp_i: ?sep:string -> (int -> 'a printer) -> 'a t printer
-(** Print an array, giving the printing function both index and item. *)
+(** [pp_i ~sep pp_item ppf a] prints the array [a] on [ppf].
+    The printing function [pp_item] is giving both index and element.
+    Elements are separated by [sep] (defaults to ", "). *)
 
 val map : f:('a -> 'b) -> 'a t -> 'b t
-(** [map f a] applies function [f] to all the elements of [a],
+(** [map ~f a] applies function [f] to all elements of [a],
-    and builds an array with the results returned by [f]:
+    and builds an array with the results returned by [~f]:
-    [[| f a.(0); f a.(1); ...; f a.(length a - 1) |]]. *)
+    [[| ~f a.(0); ~f a.(1); ...; ~f a.(length a - 1) |]]. *)
 
 val map2 : f:('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
-(** [map2 f a b] applies function [f] to all the elements of [a] and [b],
+(** [map2 ~f a b] applies function [~f] to all elements of [a] and [b],
-    and builds an array with the results returned by [f]:
+    and builds an array with the results returned by [~f]:
-    [[| f a.(0) b.(0); ...; f a.(length a - 1) b.(length b - 1)|]].
+    [[| ~f a.(0) b.(0); ...; ~f a.(length a - 1) b.(length b - 1)|]].
-      @raise Invalid_argument if they have distinct lengths.
+
+      @raise Invalid_argument if [a] and [b] have distinct lengths.
       @since 0.20 *)
 
 val rev : 'a t -> 'a t
-(** Copy + reverse in place.
+(** [rev a] copies the array [a] and reverses it in place.
     @since 0.20 *)
 
 val filter : f:('a -> bool) -> 'a t -> 'a t
-(** Filter elements out of the array. Only the elements satisfying
+(** [filter ~f a] filters elements out of the array [a]. Only the elements satisfying
-    the given predicate will be kept. *)
+    the given predicate [~f] will be kept. *)
 
 val filter_map : f:('a -> 'b option) -> 'a t -> 'b t
-(** Map each element into another value, or discard it. *)
+(** [filter_map ~f [|a1; ...; an|]] calls [(~f a1) ... (~f an)] and returns an array [b] consisting
+    of all elements [bi] such as [~f ai = Some bi]. When [~f] returns [None], the corresponding
+    element of [a] is discarded. *)
 
 val flat_map : f:('a -> 'b t) -> 'a t -> 'b array
-(** Transform each element into an array, then flatten. *)
+(** [flat_map ~f a] transforms each element of [a] into an array, then flattens. *)
 
 val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
-(** Infix version of {!flat_map}. *)
+(** [a >>= f] is the infix version of {!flat_map}. *)
 
 val (>>|) : 'a t -> ('a -> 'b) -> 'b t
-(** Infix version of {!map}.
+(** [a >>| f] is the infix version of {!map}.
     @since 0.8 *)
 
 val (>|=) : 'a t -> ('a -> 'b) -> 'b t
-(** Infix version of {!map}.
+(** [a >|= f] is the infix version of {!map}.
     @since 0.8 *)
 
 val except_idx : 'a t -> int -> 'a list
-(** Remove given index, obtaining the list of the other elements. *)
+(** [except_idx a i] removes the element of [a] at given index [i], and returns
+    the list of the other elements. *)
 
 val (--) : int -> int -> int t
-(** Range array. Bounds included. *)
+(** [x -- y] creates an array containing integers in the range [x .. y]. Bounds included. *)
 
 val (--^) : int -> int -> int t
-(** Range array, excluding right bound.
+(** [x --^ y] creates an array containing integers in the range [x .. y]. Right bound excluded.
     @since 0.17 *)
 
 val random : 'a random_gen -> 'a t random_gen
@@ -311,7 +331,7 @@ end
 val sort_generic :
   (module MONO_ARRAY with type t = 'arr and type elt = 'elt) ->
   cmp:('elt -> 'elt -> int) -> 'arr -> unit
-(** Sort the array, without allocating (eats stack space though). Performance
+(** [sort_generic (module M) ~cmp a] sorts the array [a], without allocating (eats stack space though).
-    might be lower than {!Array.sort}.
+    Performance might be lower than {!Array.sort}.
     @since 0.14 *)
 

src/core/CCArray_slice.ml

@@ -28,7 +28,7 @@ let empty = {
 }
 
 let make arr i ~len =
-  if i<0||i+len > Array.length arr then invalid_arg "Array_slice.make";
+  if i<0||i+len > Array.length arr then invalid_arg "CCArray_slice.make";
   { arr; i; j=i+len; }
 
 let of_slice (arr,i,len) = make arr i ~len
@@ -113,7 +113,7 @@ let fold_while f acc a =
 
 let get a i =
   let j = a.i + i in
-  if i<0 || j>=a.j then invalid_arg "Array_slice.get";
+  if i<0 || j>=a.j then invalid_arg "CCArray_slice.get";
   a.arr.(j)
 
 let get_safe a i =
@@ -136,7 +136,7 @@ let get_safe a i =
 
 let set a i x =
   let j = a.i + i in
-  if i<0 || j>=a.j then invalid_arg "Array_slice.set";
+  if i<0 || j>=a.j then invalid_arg "CCArray_slice.set";
   a.arr.(j) <- x
 
 let iter f a =
@@ -146,7 +146,7 @@ let iteri f a =
   for k=0 to length a-1 do f k a.arr.(a.i + k) done
 
 let blit a i b j len =
-  if i+len>length a || j+len>length b then invalid_arg "Array_slice.blit";
+  if i+len>length a || j+len>length b then invalid_arg "CCArray_slice.blit";
   Array.blit a.arr (a.i+i) b.arr (b.i+j) len
 
 let rec _find f a i j =
@@ -382,7 +382,7 @@ let _iter2 f a b i j ~len =
   done
 
 let iter2 f a b =
-  if length a <> length b then invalid_arg "iter2";
+  if length a <> length b then invalid_arg "CCArray_slice_iter2";
   _iter2 f a.arr b.arr a.i b.i ~len:(length a)
 
 let _fold2 f acc a b i j ~len =
@@ -395,7 +395,7 @@ let _fold2 f acc a b i j ~len =
   aux acc 0
 
 let fold2 f acc a b =
-  if length a <> length b then invalid_arg "fold2";
+  if length a <> length b then invalid_arg "CCArray_slice_fold2";
   _fold2 f acc a.arr b.arr a.i b.i ~len:(length a)
 
 let shuffle a =

src/core/CCArray_slice.mli

@@ -12,225 +12,248 @@ type 'a random_gen = Random.State.t -> 'a
 type 'a printer = Format.formatter -> 'a -> unit
 
 type 'a t
-(** Array slice, containing elements of type ['a]. *)
+(** The type for an array slice, containing elements of type ['a] *)
 
 val empty : 'a t
-(** The empty array slice. *)
+(** [empty] is the empty array slice. *)
 
 val equal : 'a equal -> 'a t equal
+(** [equal eq as1 as2] is [true] if the lengths of [as1] and [as2] are the same
+    and if the corresponding elements test equal using [eq]. *)
 
 val compare : 'a ord -> 'a t ord
+(** [compare cmp as1 as2] compares the two slices [as1] and [as2] using 
+    the comparison function [cmp], element by element. *)
 
 val get : 'a t -> int -> 'a
-(** [get a n] returns the element number [n] of array [a].
+(** [get as n] returns the element number [n] of slice [as].
     The first element has number 0.
-    The last element has number [length a - 1].
+    The last element has number [length as - 1].
-    You can also write [a.(n)] instead of [get a n].
+    You can also write [as.(n)] instead of [get as n].
 
     Raise [Invalid_argument "index out of bounds"]
-    if [n] is outside the range 0 to [(length a - 1)]. *)
+    if [n] is outside the range 0 to [(length as - 1)]. *)
 
 val get_safe : 'a t -> int -> 'a option
-(** [get_safe a i] returns [Some a.(i)] if [i] is a valid index.
+(** [get_safe as i] returns [Some as.(i)] if [i] is a valid index.
     @since 0.18 *)
 
 val make : 'a array -> int -> len:int -> 'a t
-(** Create a slice from given offset and length.
+(** [make a i ~len] creates a slice from given offset [i] and length [len] of the given array [a].
     @raise Invalid_argument if the slice isn't valid. *)
 
 val of_slice : ('a array * int * int) -> 'a t
-(** Make a sub-array from a triple [(arr, i, len)] where [arr] is the array,
+(** [of_slice (a, i, len)] makes a slice from a triple [(a, i, len)] where [a] is the array,
-    [i] the offset in [arr], and [len] the number of elements of the slice.
+    [i] the offset in [a], and [len] the number of elements of the slice.
     @raise Invalid_argument if the slice isn't valid (See {!make}). *)
 
 val to_slice : 'a t -> ('a array * int * int)
-(** Convert into a triple [(arr, i, len)] where [len] is the length of
+(** [to_slice as] converts the slice [as] into a triple [(a, i, len)] where [len] is the length of
-    the sub-array of [arr] starting at offset [i]. *)
+    the sub-array of [a] starting at offset [i]. *)
 
 val to_list : 'a t -> 'a list
-(** Convert directly to a list.
+(** [to_list as] converts the slice [as] directly to a list.
     @since 1.0 *)
 
 val full : 'a array -> 'a t
-(** Slice that covers the full array. *)
+(** [full a] creates a slice that covers the full array [a]. *)
 
 val underlying : 'a t -> 'a array
-(** Underlying array (shared). Modifying this array will modify the slice. *)
+(** [underlying as] returns the underlying array (shared). Modifying this array will modify
+    the slice [as]. *)
 
 val copy : 'a t -> 'a array
-(** Copy into a new array. *)
+(** [copy as] copies the slice [as] into a new array. *)
 
 val sub : 'a t -> int -> int -> 'a t
-(** Sub-slice. *)
+(** [sub as i len] builds a new sub-slice that contains the given subrange specified
+    by the index [i] and the length [len]. *)
 
 val set : 'a t -> int -> 'a -> unit
-(** [set a n x] modifies array [a] in place, replacing
+(** [set as n x] modifies the slice [as] in place, replacing
     element number [n] with [x].
-    You can also write [a.(n) <- x] instead of [set a n x].
+    You can also write [as.(n) <- x] instead of [set as n x].
 
     Raise [Invalid_argument "index out of bounds"]
-    if [n] is outside the range 0 to [length a - 1]. *)
+    if [n] is outside the range 0 to [length as - 1]. *)
 
 val length : _ t -> int
-(** Return the length (number of elements) of the given array. *)
+(** [length as] returns the length (number of elements) of the given slice [as]. *)
 
 val fold : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a
-(** [fold f x a] computes [f (... (f (f x a.(0)) a.(1)) ...) a.(n-1)],
+(** [fold f acc as] computes [f (... (f (f acc as.(0)) as.(1)) ...) as.(length as - 1)]. *)
-    where [n] is the length of the array [a]. *)
 
 val foldi : ('a -> int -> 'b -> 'a) -> 'a -> 'b t -> 'a
-(** Fold left on array, with index. *)
+(** [foldi f acc as] is just like {!fold} but it also passes in the index of each element
+    as the second argument to the folded function [f]. *)
 
 val fold_while : ('a -> 'b -> 'a * [`Stop | `Continue]) -> 'a -> 'b t -> 'a
-(** Fold left on array until a stop condition via [('a, `Stop)] is
+(** [fold_while f acc as] folds left on slice [as] until a stop condition via [('a, `Stop)]
-    indicated by the accumulator.
+    is indicated by the accumulator.
     @since 0.8 *)
 
 val iter : ('a -> unit) -> 'a t -> unit
-(** [iter f a] applies function [f] in turn to all
+(** [iter f as] applies function [f] in turn to all elements of [as].
-    the elements of [a].  It is equivalent to
+    It is equivalent to [f as.(0); f as.(1); ...; f as.(length as - 1); ()]. *)
-    [f a.(0); f a.(1); ...; f a.(length a - 1); ()]. *)
 
 val iteri : (int -> 'a -> unit) -> 'a t -> unit
-(** Like {!Array.iter}, but the
+(** [iteri f as] is like {!iter}, but the function [f] is applied with the index of the element
-    function is applied with the index of the element as first argument,
+    as first argument, and the element itself as second argument. *)
-    and the element itself as second argument. *)
 
 val blit : 'a t -> int -> 'a t -> int -> int -> unit
-(** [blit v1 o1 v2 o2 len] copies [len] elements
+(** [blit as1 o1 as2 o2 len] copies [len] elements
-    from array [v1], starting at element number [o1], to array [v2],
+    from slice [as1], starting at element number [o1], to slice [as2],
     starting at element number [o2]. It works correctly even if
-    [v1] and [v2] are the same array, and the source and
+    [as1] and [as2] are the same slice, and the source and
     destination chunks overlap.
 
-    Raise [Invalid_argument "Array.blit"] if [o1] and [len] do not
+    Raise [Invalid_argument "CCArray_slice.blit"] if [o1] and [len] do not
-    designate a valid subarray of [v1], or if [o2] and [len] do not
+    designate a valid subarray of [as1], or if [o2] and [len] do not
-    designate a valid subarray of [v2]. *)
+    designate a valid subarray of [as2]. *)
 
 val reverse_in_place : 'a t -> unit
-(** Reverse the array in place. *)
+(** [reverse_in_place as] reverses the slice [as] in place. *)
 
 val sorted : ('a -> 'a -> int) -> 'a t -> 'a array
-(** [sorted cmp a] makes a copy of [a] and sorts it with [cmp].
+(** [sorted cmp as] makes a copy of [as] and sorts it with [cmp].
     @since 1.0 *)
 
 val sort_indices : ('a -> 'a -> int) -> 'a t -> int array
-(** [sort_indices cmp a] returns a new array [b], with the same length as [a],
+(** [sort_indices cmp as] returns a new array [b], with the same length as [as],
-    such that [b.(i)] is the index at which the [i]-th element of [sorted cmp a]
+    such that [b.(i)] is the index at which the [i]-th element of [sorted cmp as]
-    appears in [a]. [a] is not modified.
+    appears in [as]. [as] is not modified.
 
-    In other words, [map (fun i -> a.(i)) (sort_indices cmp a) = sorted cmp a].
+    In other words, [map (fun i -> as.(i)) (sort_indices cmp as) = sorted cmp as].
     [sort_indices] yields the inverse permutation of {!sort_ranking}.
     @since 1.0 *)
 
 val sort_ranking : ('a -> 'a -> int) -> 'a t -> int array
-(** [sort_ranking cmp a] returns a new array [b], with the same length as [a],
+(** [sort_ranking cmp as] returns a new array [b], with the same length as [as],
-    such that [b.(i)] is the index at which the [i]-th element of [a] appears
+    such that [b.(i)] is the index at which the [i]-th element of [as] appears
-    in [sorted cmp a]. [a] is not modified.
+    in [sorted cmp as]. [as] is not modified.
 
-    In other words, [map (fun i -> (sorted cmp a).(i)) (sort_ranking cmp a) = a].
+    In other words, [map (fun i -> (sorted cmp as).(i)) (sort_ranking cmp as) = as].
     [sort_ranking] yields the inverse permutation of {!sort_indices}.
 
-    In the absence of duplicate elements in [a], we also have
+    In the absence of duplicate elements in [as], we also have
-    [lookup_exn a.(i) (sorted a) = (sorted_ranking a).(i)].
+    [lookup_exn as.(i) (sorted as) = (sorted_ranking as).(i)].
     @since 1.0 *)
 
 val find : ('a -> 'b option) -> 'a t -> 'b option
-(** [find f a] returns [Some y] if there is an element [x] such
+(** [find f as] returns [Some y] if there is an element [x] such
-    that [f x = Some y], else it returns [None]. *)
+    that [f x = Some y]. Otherwise returns [None]. *)
 
 val findi : (int -> 'a -> 'b option) -> 'a t -> 'b option
-(** Like {!find}, but also pass the index to the predicate function.
+(** [findi f as] is like {!find}, but the index of the element is also passed 
+    to the predicate function [f].
     @since 0.3.4 *)
 
 val find_idx : ('a -> bool) -> 'a t -> (int * 'a) option
-(** [find_idx p x] returns [Some (i,x)] where [x] is the [i]-th element of [l],
+(** [find_idx p as] returns [Some (i,x)] where [x] is the [i]-th element of [as],
     and [p x] holds. Otherwise returns [None].
     @since 0.3.4 *)
 
 val lookup : cmp:'a ord -> 'a -> 'a t -> int option
-(** Lookup the index of some value in a sorted array.
+(** [lookup ~cmp x as] lookups the index [i] of some key [x] in the slice [as], provided [as] is
-    @return [None] if the key is not present, or
+    sorted using [cmp].
+    @return [None] if the key [x] is not present, or
       [Some i] ([i] the index of the key) otherwise. *)
 
 val lookup_exn : cmp:'a ord -> 'a -> 'a t -> int
-(** Like {!lookup}, but
+(** [lookup_exn ~cmp x as] is like {!lookup}, but
-    @raise Not_found if the key is not present. *)
+    @raise Not_found if the key [x] is not present. *)
 
 val bsearch : cmp:('a -> 'a -> int) -> 'a -> 'a t ->
   [ `All_lower | `All_bigger | `Just_after of int | `Empty | `At of int ]
-(** [bsearch ?cmp x arr] finds the index of the object [x] in the array [arr],
+(** [bsearch ~cmp x as] finds the index of the object [x] in the slice [as],
-    provided [arr] is {b sorted} using [cmp]. If the array is not sorted,
+    provided [as] is {b sorted} using [cmp]. If the slice is not sorted,
     the result is not specified (may raise Invalid_argument).
 
-    Complexity: [O(log n)] where n is the length of the array
+    Complexity: [O(log n)] where n is the length of the slice [as]
     (dichotomic search).
 
     @return
-    - [`At i] if [cmp arr.(i) x = 0] (for some i).
+    - [`At i] if [cmp as.(i) x = 0] (for some i).
-    - [`All_lower] if all elements of [arr] are lower than [x].
+    - [`All_lower] if all elements of [as] are lower than [x].
-    - [`All_bigger] if all elements of [arr] are bigger than [x].
+    - [`All_bigger] if all elements of [as] are bigger than [x].
-    - [`Just_after i] if [arr.(i) < x < arr.(i+1)].
+    - [`Just_after i] if [as.(i) < x < as.(i+1)].
-    - [`Empty] if the array is empty.
+    - [`Empty] if the slice [as] is empty.
 
-    @raise Invalid_argument if the array is found to be unsorted w.r.t [cmp].
+    @raise Invalid_argument if the slice is found to be unsorted w.r.t [cmp].
     @since 0.13 *)
 
 val for_all : ('a -> bool) -> 'a t -> bool
-(** [for_all p [|a1; ...; an|]] checks if all elements of the array
+(** [for_all p [|as1; ...; asn|]] checks if all elements of the slice
     satisfy the predicate [p]. That is, it returns
-    [(p a1) && (p a2) && ... && (p an)]. *)
+    [(p as1) && (p as2) && ... && (p asn)]. *)
 
 val for_all2 : ('a -> 'b -> bool) -> 'a t -> 'b t -> bool
-(** Forall on pairs of arrays.
+(** [for_all2 p [|as1; ...; asn|] [|bs1; ...; bsn|]] is [true] if each pair of elements [asi bsi]
-    @raise Invalid_argument if they have distinct lengths.
+    satisfies the predicate [p].
+    That is, it returns [(p as1 bs1) && (p as2 bs2) && ... && (p asn bsn)].
+
+    @raise Invalid_argument if slices have distinct lengths.
     Allow different types.
     @since 0.20 *)
 
 val exists : ('a -> bool) -> 'a t -> bool
-(** [exists p [|a1; ...; an|]] checks if at least one element of
+(** [exists p [|as1; ...; asn|]] is [true] if at least one element of
-    the array satisfies the predicate [p]. That is, it returns
+    the slice satisfies the predicate [p]. That is, it returns
-    [(p a1) || (p a2) || ... || (p an)]. *)
+    [(p as1) || (p as2) || ... || (p asn)]. *)
 
 val exists2 : ('a -> 'b -> bool) -> 'a t -> 'b t -> bool
-(** Exists on pairs of arrays.
+(** [exists2 p [|as1; ...; asn|] [|bs1; ...; bsn|]] is [true] if any pair of elements [asi bsi]
-    @raise Invalid_argument if they have distinct lengths.
+    satisfies the predicate [p].
+    That is, it returns [(p as1 bs1) || (p as2 bs2) || ... || (p asn bsn)].
+
+    @raise Invalid_argument if slices have distinct lengths.
     Allow different types.
     @since 0.20 *)
 
 val fold2 : ('acc -> 'a -> 'b -> 'acc) -> 'acc -> 'a t -> 'b t -> 'acc
-(** Fold on two arrays stepwise.
+(** [fold2 f acc as bs] fold on two slices [as] and [bs] stepwise.
-    @raise Invalid_argument if they have distinct lengths.
+    It computes [f (... (f acc as1 bs1)...) asn bsn].
+
+    @raise Invalid_argument if slices have distinct lengths.
     @since 0.20 *)
 
 val iter2 : ('a -> 'b -> unit) -> 'a t -> 'b t -> unit
-(** Iterate on two arrays stepwise.
+(** [iter2 f as bs] iterates on the two slices [as] and [bs] stepwise.
-    @raise Invalid_argument if they have distinct lengths.
+    It is equivalent to  [f as0 bs0; ...; f as.(length as - 1) bs.(length bs - 1); ()].
+
+    @raise Invalid_argument if slices have distinct lengths.
     @since 0.20 *)
 
 val shuffle : 'a t -> unit
-(** Shuffle randomly the array, in place. *)
+(** [shuffle as] randomly shuffles the slice [as], in place. *)
 
 val shuffle_with : Random.State.t -> 'a t -> unit
-(** Like {!shuffle} but using a specialized random state. *)
+(** [shuffle_with rs as] randomly shuffles the slice [as] (like {!shuffle}) but a specialized random
+    state [rs] is used to control the random numbers being produced during shuffling (for reproducibility). *)
 
 val random_choose : 'a t -> 'a random_gen
-(** Choose an element randomly.
+(** [random_choose as rs] randomly chooses an element of [as].
     @raise Not_found if the array/slice is empty. *)
 
 val to_seq : 'a t -> 'a sequence
-(** Return a [sequence] of the elements of a slice. *)
+(** [to_seq as] returns a [sequence] of the elements of a slice [as].
+    The input slice [as] is shared with the sequence and modification of it will result
+    in modification of the sequence. *)
 
 val to_gen : 'a t -> 'a gen
-(** Return a [gen] of the elements of a slice. *)
+(** [to_gen as] returns a [gen] of the elements of a slice [as]. *)
 
 val to_klist : 'a t -> 'a klist
-(** Return a [klist] of the elements of a slice. *)
+(** [to_klist as] returns a [klist] of the elements of a slice [as]. *)
 
 (** {2 IO} *)
 
 val pp: ?sep:string -> 'a printer -> 'a t printer
-(** Print an array of items with printing function. *)
+(** [pp ~sep pp_item ppf as] formats the slice [as] on [ppf].
+    Each element is formatted with [pp_item] and elements are separated
+    by [sep] (defaults to ", "). *)
 
 val pp_i: ?sep:string -> (int -> 'a printer) -> 'a t printer
-(** Print an array, giving the printing function both index and item. *)
+(** [pp_i ~sep pp_item ppf as] prints the slice [as] on [ppf].
+    The printing function [pp_item] is giving both index and element.
+    Elements are separated by [sep] (defaults to ", "). *)