From 1727cc81993b280ed161d1ff3efb9b89baf997f7 Mon Sep 17 00:00:00 2001
From: JPR <jprodi04@gmail.com>
Date: Mon, 9 Apr 2018 00:08:31 +0200
Subject: [PATCH] Few Comments corrections

---
 src/core/CCArray.mli             |  8 ++++----
 src/core/CCArrayLabels.mli       |  6 +++---
 src/core/CCArray_slice.mli       |  2 +-
 src/core/CCFormat.mli            |  3 +++
 src/core/CCHeap.mli              |  2 +-
 src/core/CCInt.mli               | 13 +++++++++++++
 src/core/CCInt64.mli             |  8 ++++----
 src/core/CCList.mli              | 10 +++++-----
 src/core/CCListLabels.mli        | 15 ++++++++++++---
 src/core/CCOpt.mli               |  4 ++--
 src/core/CCParse.mli             |  2 +-
 src/core/CCRef.mli               |  2 +-
 src/core/CCSet.mli               |  2 +-
 src/core/CCString.mli            |  8 ++++----
 src/core/CCUtf8_string.mli       |  4 ++--
 src/data/CCBijection.mli         | 26 +++++++++++++-------------
 src/data/CCDeque.mli             | 14 +++++++-------
 src/data/CCPersistentHashtbl.mli |  2 +-
 src/data/CCSimple_queue.mli      |  3 +++
 19 files changed, 81 insertions(+), 53 deletions(-)

diff --git a/src/core/CCArray.mli b/src/core/CCArray.mli
index 14c9edf9..5df5484a 100644
--- a/src/core/CCArray.mli
+++ b/src/core/CCArray.mli
@@ -116,7 +116,7 @@ val sort_indices : ('a -> 'a -> int) -> 'a t -> int array
 
 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],
-    such that [b.(i)] is the index at which the [i]-the element of [a] appears
+    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 other words, [map (fun i -> (sorted cmp a).(i)) (sort_ranking cmp a) = a].
@@ -133,7 +133,7 @@ val find_map : ('a -> 'b option) -> 'a t -> 'b option
 
 val find : ('a -> 'b option) -> 'a t -> 'b option
 (** Alias to {!find_map}.
-    @deprecated since 1.3 *)
+    @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.
@@ -142,7 +142,7 @@ val find_map_i : (int -> 'a -> 'b option) -> 'a t -> 'b option
 val findi : (int -> 'a -> 'b option) -> 'a t -> 'b option
 (** Alias to {!find_map_i}.
     @since 0.3.4
-    @deprecated since 1.3 *)
+    @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],
@@ -164,7 +164,7 @@ 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],
     provided [arr] is {b sorted} using [cmp]. If the array is not sorted,
-    the result is not specified
+    the result is not specified.
 
     Complexity: [O(log n)] where n is the length of the array
     (dichotomic search).
diff --git a/src/core/CCArrayLabels.mli b/src/core/CCArrayLabels.mli
index 51cfac5f..653ef5e6 100644
--- a/src/core/CCArrayLabels.mli
+++ b/src/core/CCArrayLabels.mli
@@ -117,7 +117,7 @@ val sort_indices : f:('a -> 'a -> int) -> 'a t -> int array
 
 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],
-    such that [b.(i)] is the index at which the [i]-the element of [a] appears
+    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 other words, [map (fun i -> (sorted cmp a).(i)) (sort_ranking cmp a) = a].
@@ -135,7 +135,7 @@ val find_map : f:('a -> 'b option) -> 'a t -> 'b option
 val find : f:('a -> 'b option) -> 'a t -> 'b option
 (** [find f a] returns [Some y] if there is an element [x] such
     that [f x = Some y], else it returns [None].
-    @deprecated since 2.1 *)
+    @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.
@@ -144,7 +144,7 @@ val find_map_i : f:(int -> 'a -> 'b option) -> 'a t -> 'b option
 val findi : f:(int -> 'a -> 'b option) -> 'a t -> 'b option
 (** Like {!find}, but also pass the index to the predicate function.
     @since 0.3.4
-    @deprecated since 2.1 *)
+    @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],
diff --git a/src/core/CCArray_slice.mli b/src/core/CCArray_slice.mli
index 109571fd..1c95e1ef 100644
--- a/src/core/CCArray_slice.mli
+++ b/src/core/CCArray_slice.mli
@@ -125,7 +125,7 @@ val sort_indices : ('a -> 'a -> int) -> 'a t -> int array
 
 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],
-    such that [b.(i)] is the index at which the [i]-the element of [a] appears
+    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 other words, [map (fun i -> (sorted cmp a).(i)) (sort_ranking cmp a) = a].
diff --git a/src/core/CCFormat.mli b/src/core/CCFormat.mli
index 9baaff0b..506b6aa7 100644
--- a/src/core/CCFormat.mli
+++ b/src/core/CCFormat.mli
@@ -47,8 +47,11 @@ val text : string printer
     @since 1.2 *)
 
 val char : char printer (** @since 0.14 *)
+
 val int32 : int32 printer (** @since 0.14 *)
+
 val int64 : int64 printer (** @since 0.14 *)
+
 val nativeint : nativeint printer (** @since 0.14 *)
 
 val flush : unit printer
diff --git a/src/core/CCHeap.mli b/src/core/CCHeap.mli
index ff132cfd..16bb1452 100644
--- a/src/core/CCHeap.mli
+++ b/src/core/CCHeap.mli
@@ -132,7 +132,7 @@ module type S = sig
   (** Return a [ktree] of the elements of the heap. *)
 
   val pp : ?sep:string -> elt printer -> t printer
-  (** printer
+  (** Printer.
       Renamed from {!print} since 2.0
       @since 0.16 *)
 end
diff --git a/src/core/CCInt.mli b/src/core/CCInt.mli
index de926e90..48ef8ac4 100644
--- a/src/core/CCInt.mli
+++ b/src/core/CCInt.mli
@@ -117,18 +117,31 @@ module Infix : sig
       @since 1.2 *)
 
   val (+) : t -> t -> t (** @since 2.1 *)
+
   val (-) : t -> t -> t (** @since 2.1 *)
+
   val (~-) : t -> t (** @since 2.1 *)
+
   val ( * ) : t -> t -> t (** @since 2.1 *)
+
   val (/) : t -> t -> t (** @since 2.1 *)
+
   val (mod) : t -> t -> t (** @since 2.1 *)
+
   val (land) : t -> t -> t (** @since 2.1 *)
+
   val (lor) : t -> t -> t (** @since 2.1 *)
+
   val (lxor) : t -> t -> t (** @since 2.1 *)
+
   val lnot : t -> t (** @since 2.1 *)
+
   val (lsl) : t -> int -> t (** @since 2.1 *)
+
   val (lsr) : t -> int -> t (** @since 2.1 *)
+
   val (asr) : t -> int -> t (** @since 2.1 *)
+
 end
 
 include module type of Infix
diff --git a/src/core/CCInt64.mli b/src/core/CCInt64.mli
index a6b31951..6d6b7214 100644
--- a/src/core/CCInt64.mli
+++ b/src/core/CCInt64.mli
@@ -119,7 +119,7 @@ val of_int : int -> t
 
 val of_int_exn : int -> t
 (** Alias to {!Int64.of_int}.
-    @deprecated since 2.1 *)
+    @deprecated since 2.1, use {!Int64.of_int} instead. *)
 
 val to_int32 : t -> int32
 (** Convert the given 64-bit integer (type [int64]) to a
@@ -133,7 +133,7 @@ val of_int32 : int32 -> t
 
 val of_int32_exn : int32 -> t
 (** Alias to {!Int64.of_int32}.
-    @deprecated since 2.1 *)
+    @deprecated since 2.1, use {!Int64.of_int32} instead. *)
 
 val to_nativeint : t -> nativeint
 (** Convert the given 64-bit integer (type [int64]) to a
@@ -147,7 +147,7 @@ val of_nativeint : nativeint -> t
 
 val of_nativeint_exn : nativeint -> t
 (** Alias to {!Int64.of_nativeint}.
-    @deprecated since 2.1 *)
+    @deprecated since 2.1, use {!Int64.of_nativeint} instead. *)
 
 val to_float : t -> float
 (** Convert the given 64-bit integer to a floating-point number. *)
@@ -162,7 +162,7 @@ val of_float : float -> t
 
 val of_float_exn : float -> t
 (** Alias to {!Int64.of_float}.
-    @deprecated since 2.1 *)
+    @deprecated since 2.1, use {!Int64.of_float} instead. *)
 
 val to_string : t -> string
 (** Return the string representation of its argument, in decimal. *)
diff --git a/src/core/CCList.mli b/src/core/CCList.mli
index ddaa6eab..c1f4e5c2 100644
--- a/src/core/CCList.mli
+++ b/src/core/CCList.mli
@@ -14,7 +14,7 @@ include module type of List
 type 'a t = 'a list
 
 val empty : 'a t
-(** [empty] is []. *)
+(** [empty] is [[]]. *)
 
 val is_empty : _ t -> bool
 (** [is_empty l] returns [true] iff [l = []].
@@ -203,12 +203,12 @@ val sublists_of_len :
     @since 1.0 *)
 
 val intersperse : 'a -> 'a list -> 'a list
-(** Insert the first argument between every element of the list
+(** Insert the first argument between every element of the list.
     @since 2.1 *)
 
 val interleave : 'a list -> 'a list -> 'a list
 (** [interleave [x1…xn] [y1…ym]] is [x1,y1,x2,y2,…] and finishes with
-    the suffix of the longest list
+    the suffix of the longest list.
     @since 2.1 *)
 
 val pure : 'a -> 'a t
@@ -255,7 +255,7 @@ val take_drop_while : ('a -> bool) -> 'a t -> 'a t * 'a t
 
 val last : int -> 'a t -> 'a t
 (** [last n l] takes the last [n] elements of [l] (or less if
-    [l] doesn't have that many elements. *)
+    [l] doesn't have that many elements). *)
 
 val head_opt : 'a t -> 'a option
 (** First element.
@@ -630,7 +630,7 @@ module Infix : sig
   (** As {!append}. Concatenate two lists. *)
 
   val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
-  (** [fun <*> l] is [product (fun f x -> f x) funs l]. *)
+  (** [funs <*> l] is [product (fun f x -> f x) funs l]. *)
 
   val (<$>) : ('a -> 'b) -> 'a t -> 'b t
   (** As {!map}. *)
diff --git a/src/core/CCListLabels.mli b/src/core/CCListLabels.mli
index 6477295e..4a86db5a 100644
--- a/src/core/CCListLabels.mli
+++ b/src/core/CCListLabels.mli
@@ -8,7 +8,7 @@ include module type of ListLabels
 type 'a t = 'a list
 
 val empty : 'a t
-(** [empty] is []. *)
+(** [empty] is [[]]. *)
 
 val is_empty : _ t -> bool
 (** [is_empty l] returns [true] iff [l = []].
@@ -121,6 +121,15 @@ val sublists_of_len :
 
     @since 1.5 *)
 
+val intersperse : 'a -> 'a list -> 'a list
+(** Insert the first argument between every element of the list.
+    @since 2.1 *)
+
+val interleave : 'a list -> 'a list -> 'a list
+(** [interleave [x1…xn] [y1…ym]] is [x1,y1,x2,y2,…] and finishes with
+    the suffix of the longest list.
+    @since 2.1 *)
+
 val pure : 'a -> 'a t
 (** [pure] is [return]. *)
 
@@ -161,7 +170,7 @@ val drop_while : f:('a -> bool) -> 'a t -> 'a t
 
 val last : int -> 'a t -> 'a t
 (** [last n l] takes the last [n] elements of [l] (or less if
-    [l] doesn't have that many elements. *)
+    [l] doesn't have that many elements). *)
 
 val head_opt : 'a t -> 'a option
 (** First element.
@@ -502,7 +511,7 @@ module Infix : sig
   (** As {!append}. Concatenate two lists. *)
 
   val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
-  (** [fun <*> l] is [product (fun f x -> f x) funs l]. *)
+  (** [funs <*> l] is [product (fun f x -> f x) funs l]. *)
 
   val (<$>) : ('a -> 'b) -> 'a t -> 'b t
   (** As {!map}. *)
diff --git a/src/core/CCOpt.mli b/src/core/CCOpt.mli
index 04294678..538eafaf 100644
--- a/src/core/CCOpt.mli
+++ b/src/core/CCOpt.mli
@@ -101,7 +101,7 @@ val pure : 'a -> 'a t
 (** Alias to {!return}. *)
 
 val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
-(** [f <$> (Some x)] returns [Some (f x)] and [f <$> None] returns [None]. *)
+(** [f <*> (Some x)] returns [Some (f x)] and [f <*> None] returns [None]. *)
 
 val (<$>) : ('a -> 'b) -> 'a t -> 'b t
 (** Like [map].  *)
@@ -133,7 +133,7 @@ module Infix : sig
   (** Monadic bind. *)
 
   val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
-  (** [f <$> (Some x)] returns [Some (f x)] and [f <$> None] returns [None]. *)
+  (** [f <*> (Some x)] returns [Some (f x)] and [f <*> None] returns [None]. *)
 
   val (<$>) : ('a -> 'b) -> 'a t -> 'b t
   (** Like [map].  *)
diff --git a/src/core/CCParse.mli b/src/core/CCParse.mli
index 25b997de..066a4ead 100644
--- a/src/core/CCParse.mli
+++ b/src/core/CCParse.mli
@@ -138,7 +138,7 @@ val chars1_if : (char -> bool) -> string t
 (** Like {!chars_if}, but only non-empty strings. *)
 
 val endline : char t
-(** Parses '\n'. *)
+(** Parse '\n'. *)
 
 val space : char t
 (** Tab or space. *)
diff --git a/src/core/CCRef.mli b/src/core/CCRef.mli
index 065176f7..e108316d 100644
--- a/src/core/CCRef.mli
+++ b/src/core/CCRef.mli
@@ -24,7 +24,7 @@ val update : ('a -> 'a) -> 'a t -> unit
 (** Update the reference's content with the given function. *)
 
 val incr_then_get : int t -> int
-(** [incr_then_get r] increments [r] and returns its new value, think [++ r].
+(** [incr_then_get r] increments [r] and returns its new value, think [++r].
     @since 0.17 *)
 
 val get_then_incr : int t -> int
diff --git a/src/core/CCSet.mli b/src/core/CCSet.mli
index 061b4f92..7424c0e7 100644
--- a/src/core/CCSet.mli
+++ b/src/core/CCSet.mli
@@ -68,7 +68,7 @@ module type S = sig
   val pp :
     ?start:string -> ?stop:string -> ?sep:string ->
     elt printer -> t printer
-    (** Print the set *)
+    (** Print the set. *)
 
 end
 
diff --git a/src/core/CCString.mli b/src/core/CCString.mli
index bbf5d8b1..ce807f2d 100644
--- a/src/core/CCString.mli
+++ b/src/core/CCString.mli
@@ -138,9 +138,9 @@ val replace : ?which:[`Left|`Right|`All] -> sub:string -> by:string -> string ->
 (** [replace ~sub ~by s] replaces some occurrences of [sub] by [by] in [s].
     @param which decides whether the occurrences to replace are:
       {ul
-        {- [`Left] first occurrence from the left (beginning)}
-        {- [`Right] first occurrence from the right (end)}
-        {- [`All] all occurrences (default)}
+        {- [`Left] first occurrence from the left (beginning).}
+        {- [`Right] first occurrence from the right (end).}
+        {- [`All] all occurrences (default).}
       }
     @raise Invalid_argument if [sub = ""].
     @since 0.14 *)
@@ -420,7 +420,7 @@ val split : by:string -> string -> string list
 (** {2 Utils} *)
 
 val compare_versions : string -> string -> int
-(** [compare_versions a b] compares {i version strings} [a] and [b],
+(** [compare_versions a b] compares {i version strings} [ a] and [b],
     considering that numbers are above text.
     @since 0.13 *)
 
diff --git a/src/core/CCUtf8_string.mli b/src/core/CCUtf8_string.mli
index da6caae6..8bec9722 100644
--- a/src/core/CCUtf8_string.mli
+++ b/src/core/CCUtf8_string.mli
@@ -10,9 +10,9 @@
     For more elaborate operations,
     please use the excellent {{: http://erratique.ch/software/uutf} Uutf}.
 
-    @since 2.1
+    {b status: experimental}
 
-    {b status}: experimental
+    @since 2.1
 *)
 
 
diff --git a/src/data/CCBijection.mli b/src/data/CCBijection.mli
index 470051ab..d0907bfd 100644
--- a/src/data/CCBijection.mli
+++ b/src/data/CCBijection.mli
@@ -32,40 +32,40 @@ module type S = sig
       correspond to each other. *)
 
   val cardinal : t -> int
-  (** Number of bindings. O(n) time *)
+  (** Number of bindings. O(n) time. *)
 
   val mem : left -> right -> t -> bool
-  (** Checks both sides for key membership.  *)
+  (** Check both sides for key membership. *)
 
   val mem_left : left -> t -> bool
-  (** Checks for membership of correspondence using [left] key *)
+  (** Check for membership of correspondence using [left] key. *)
 
   val mem_right : right -> t -> bool
-  (** Checks for membership of correspondence using [right] key *)
+  (** Check for membership of correspondence using [right] key. *)
 
   val find_left  : left ->  t -> right
-  (** @raise Not_found if left is not found *)
+  (** @raise Not_found if left is not found. *)
 
   val find_right : right -> t -> left
-  (** @raise Not_found if right is not found *)
+  (** @raise Not_found if right is not found. *)
 
   val remove : left -> right -> t -> t
-  (** Removes the [left], [right] binding if it exists. Returns the
+  (** Remove the [left], [right] binding if it exists. Return the
       same bijection otherwise. *)
 
   val remove_left : left -> t -> t
-  (** Remove the binding with [left] key if it exists. Returns the
-      same bijection otherwise *)
+  (** Remove the binding with [left] key if it exists. Return the
+      same bijection otherwise. *)
 
   val remove_right : right -> t -> t
-  (** Remove the binding with [right] key if it exists. Returns the
-      same bijection otherwise *)
+  (** Remove the binding with [right] key if it exists. Return the
+      same bijection otherwise. *)
 
   val list_left : t -> (left * right) list
-  (** returns the bindings as a list of ([left], [right]) values *)
+  (** Return the bindings as a list of ([left], [right]) values. *)
 
   val list_right : t -> (right * left) list
-  (** returns the bindings as a list of [(right, left)] values *)
+  (** Return the bindings as a list of [(right, left)] values. *)
 
   val add_seq : (left * right) sequence -> t -> t
 
diff --git a/src/data/CCDeque.mli b/src/data/CCDeque.mli
index db970853..73d1a619 100644
--- a/src/data/CCDeque.mli
+++ b/src/data/CCDeque.mli
@@ -28,7 +28,7 @@ val equal : eq:('a -> 'a -> bool) -> 'a t -> 'a t -> bool
     @since 0.13 *)
 
 val compare : cmp:('a -> 'a -> int) -> 'a t -> 'a t -> int
-(** [compare a b] compares lexicographically [a] and [b]
+(** [compare a b] compares lexicographically [a] and [b].
     @param cmp comparison function for elements.
     @since 0.13 *)
 
@@ -43,19 +43,19 @@ val push_back : 'a t -> 'a -> unit
 (** Push value at the back. *)
 
 val peek_front : 'a t -> 'a
-(** First value
+(** First value.
     @raise Empty if empty. *)
 
 val peek_back : 'a t -> 'a
-(** Last value
+(** Last value.
     @raise Empty if empty. *)
 
 val take_back : 'a t -> 'a
-(** Take last value
+(** Take last value.
     @raise Empty if empty. *)
 
 val take_front : 'a t -> 'a
-(** Take first value
+(** Take first value.
     @raise Empty if empty. *)
 
 val append_front : into:'a t -> 'a t -> unit
@@ -83,8 +83,8 @@ type 'a sequence = ('a -> unit) -> unit
 
 val of_seq : 'a sequence -> 'a t
 (** Create a deque from the sequence.
-    Optional argument [deque] disappears, use {!add_seq_back} instead since
-    0.13 *)
+    Optional argument [deque] disappears, use {!add_seq_back} instead.
+    @since 0.13 *)
 
 val to_seq : 'a t -> 'a sequence
 (** Iterate on the elements. *)
diff --git a/src/data/CCPersistentHashtbl.mli b/src/data/CCPersistentHashtbl.mli
index 93672157..e10b8449 100644
--- a/src/data/CCPersistentHashtbl.mli
+++ b/src/data/CCPersistentHashtbl.mli
@@ -43,7 +43,7 @@ module type S = sig
   (** Synonym to {!find} with flipped arguments. *)
 
   val get : key -> 'a t -> 'a option
-  (** Safe version of !{get_exn}. *)
+  (** Safe version of {!get_exn}. *)
 
   val mem : 'a t -> key -> bool
   (** Is the key bound? *)
diff --git a/src/data/CCSimple_queue.mli b/src/data/CCSimple_queue.mli
index 33dd8d73..a49232bb 100644
--- a/src/data/CCSimple_queue.mli
+++ b/src/data/CCSimple_queue.mli
@@ -56,8 +56,11 @@ val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
 
 module Infix : sig
   val (>|=) : 'a t -> ('a -> 'b) -> 'b t (** Alias to {!map}. *)
+
   val (@) : 'a t -> 'a t -> 'a t (** Alias to {!append}. *)
+
   val (<::) : 'a t -> 'a -> 'a t (** Alias to {!snoc}. *)
+
 end
 
 include module type of Infix