Modifs comments

src/core/CCArray.mli

@@ -297,7 +297,8 @@ val filter_map : ('a -> 'b option) -> 'a t -> 'b t
     element of [a] is discarded. *)
 
 val monoid_product : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
-(** All combinaisons of tuples from the two arrays are passed to the function
+(** [monoid_product f a b] passes all combinaisons of tuples from the two arrays [a] and [b]
+    to the function [f].
     @since 2.8 *)
 
 val flat_map : ('a -> 'b t) -> 'a t -> 'b array

src/core/CCArrayLabels.mli

@@ -313,7 +313,8 @@ val filter_map : f:('a -> 'b option) -> 'a t -> 'b t
     element of [a] is discarded. *)
 
 val monoid_product : f:('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
-(** All combinaisons of tuples from the two arrays are passed to the function
+(** [monoid_product ~f a b] passes all combinaisons of tuples from the two arrays [a] and [b] 
+    to the function [~f].
     @since 2.8 *)
 
 val flat_map : f:('a -> 'b t) -> 'a t -> 'b array

src/core/CCBool.mli

@@ -5,9 +5,10 @@
 type t = bool
 
 val compare : t -> t -> int
-(** Total ordering on booleans, similar to {!Pervasives.compare}. *)
+(** [compare b1 b2] is the total ordering on booleans [b1] and [b2], similar to {!Pervasives.compare}. *)
 
 val equal : t -> t -> bool
+(** [equal b1 b2] is [true] if [b1] and [b2] are the same. *)
 
 val to_int : t -> int
 (** [to_int true = 1], [to_int false = 0].

src/core/CCChar.mli

@@ -28,7 +28,7 @@ val to_int : t -> int
     @since 1.0 *)
 
 val to_string : t -> string
-(** [to_string c] return a string containing [c]
+(** [to_string c] returns a string containing [c]
     @since 2.7 *)
 
 val pp_buf : Buffer.t -> t -> unit

src/core/CCFloat.mli

@@ -15,47 +15,51 @@ type fpclass = Stdlib.fpclass =
   | FP_nan
 
 val nan : t
-(** Equal to {!Stdlib.nan}. *)
+(** [nan] is Not a Number (NaN). Equal to {!Stdlib.nan}. *)
 
 val max_value : t
-(** Positive infinity. Equal to {!Stdlib.infinity}. *)
+(** [max_value] is Positive infinity. Equal to {!Stdlib.infinity}. *)
 
 val min_value : t
-(** Negative infinity. Equal to {!Stdlib.neg_infinity}. *)
+(** [min_value] is Negative infinity. Equal to {!Stdlib.neg_infinity}. *)
 
 val max_finite_value : t
-(** Equal to {!Stdlib.max_float}. *)
+(** [max_finite_value] is the largest finite float value. Equal to {!Stdlib.max_float}. *)
 
 val epsilon : t
-(** The smallest positive float x such that [1.0 +. x <> 1.0].
+(** [epsilon] is the smallest positive float x such that [1.0 +. x <> 1.0].
     Equal to {!Stdlib.epsilon_float}. *)
 
 val is_nan : t -> bool
 (** [is_nan f] returns [true] if f is NaN, [false] otherwise. *)
 
 val add : t -> t -> t
-(** Equal to [(+.)]. *)
+(** [add x y] is equal to [x +. y]. *)
 
 val sub : t -> t -> t
-(** Equal to [(-.)]. *)
+(** [sub x y] is equal to [x -. y]. *)
 
 val neg : t -> t
-(** Equal to [(~-.)]. *)
+(** [neg x] is equal to [~-. x]. *)
 
 val abs : t -> t
-(** The absolute value of a floating-point number.
+(** [abs x] is the absolute value of the floating-point number [x].
     Equal to {!Stdlib.abs_float}. *)
 
 val scale : t -> t -> t
-(** Equal to [( *. )]. *)
+(** [scale x y] is equal to [x *. y]. *)
 
 val min : t -> t -> t
+(** [min x y] returns the min of the two given values [x] and [y]. *)
 
 val max : t -> t -> t
+(** [max x y] returns the max of the two given values [x] and [y]. *)
 
 val equal : t -> t -> bool
+(** [equal x y] is [true] if [x] and [y] are the same. *)
 
 val compare : t -> t -> int
+(** [compare x y] is {!Stdlib.compare x y}. *)
 
 type 'a printer = Format.formatter -> 'a -> unit
 type 'a random_gen = Random.State.t -> 'a
@@ -73,7 +77,7 @@ val fsign : t -> t
     @since 0.7 *)
 
 val round : t -> t
-(** [round f] returns the closest integer value, either above or below.
+(** [round x] returns the closest integer value, either above or below.
     For [n + 0.5], [round] returns [n].
     @since 0.20 *)
 
@@ -112,7 +116,7 @@ val equal_precision : epsilon:t -> t -> t -> bool
 (** Equality with allowed error up to a non negative epsilon value. *)
 
 val classify : t -> fpclass
-(** Return the class of the given floating-point number:
+(** [classify x] returns the class of the given floating-point number [x]:
     normal, subnormal, zero, infinite or nan (not a number). *)
 
 (** {2 Infix Operators}

src/core/CCFormat.mli

@@ -38,7 +38,7 @@ val newline : unit printer
     @since 1.2 *)
 
 val substring : (string * int * int) printer
-(** Print the substring [(s,i,len)], where [i] is the offset
+(** [substring (s,i,len)] prints the substring [(s,i,len)], where [i] is the offset
     in [s] and [len] the number of bytes in the substring.
     @raise Invalid_argument if the triple [(s,i,len)] does not
     describe a proper substring.

src/core/CCFun.mli

@@ -6,10 +6,10 @@
 include module type of CCShimsFun_
 
 val (|>) : 'a -> ('a -> 'b) -> 'b
-(** A 'pipe' operator. [x |> f] is the same as [f x]. *)
+(** [x |> f] is the same as [f x]. A 'pipe' operator. *)
 
 val compose : ('a -> 'b) -> ('b -> 'c) -> 'a -> 'c
-(** Composition. [compose f g x] is [g (f x)]. *)
+(** [compose f g x] is [g (f x)]. Composition. *)
 
 val compose_binop : ('a -> 'b) -> ('b -> 'b -> 'c) -> 'a -> 'a -> 'c
 (** [compose_binop f g] is [fun x y -> g (f x) (f y)].
@@ -18,19 +18,19 @@ val compose_binop : ('a -> 'b) -> ('b -> 'b -> 'c) -> 'a -> 'a -> 'c
     @since 0.6*)
 
 val (%>) : ('a -> 'b) -> ('b -> 'c) -> 'a -> 'c
-(** Alias to [compose]. *)
+(** [(f %> g) x] or [(%>) f g x] is [g (f x)]. Alias to [compose]. *)
 
 val (@@) : ('a -> 'b) -> 'a -> 'b
 (** [f @@ x] is the same as [f x], but right-associative.
     @since 0.5 *)
 
 val curry : ('a * 'b -> 'c) -> 'a -> 'b -> 'c
-(** Convert a function which accepts a pair of arguments into a function which accepts two arguments.
+(** [curry f x y] is [f (x,y)].
-    [curry f x y] is [f (x,y)]. *)
+    Convert a function which accepts a pair of arguments into a function which accepts two arguments. *)
 
 val uncurry : ('a -> 'b -> 'c) -> ('a * 'b) -> 'c
-(** Convert a function which accepts a two arguments into a function which accepts a pair of arguments.
+(** [uncurry f (x,y)] is  [f x y].
-    [uncurry f (x,y)] is  [f x y]. *)
+    Convert a function which accepts a two arguments into a function which accepts a pair of arguments. *)
 
 val tap : ('a -> _) -> 'a -> 'a
 (** [tap f x] evaluates [f x], discards it, then returns [x]. Useful
@@ -42,13 +42,13 @@ val tap : ('a -> _) -> 'a -> 'a
 *)
 
 val (%) : ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c
-(** Mathematical composition. [(%) f g x] is [f (g x)]. *)
+(** [(f % g) x] or [(%) f g x] is [f (g x)]. Mathematical composition. *)
 
 val lexicographic : ('a -> 'a -> int) -> ('a -> 'a -> int) -> 'a -> 'a -> int
 (** Lexicographic combination of comparison functions. *)
 
 val finally : h:(unit -> _) -> f:(unit -> 'a) -> 'a
-(** [finally h f] calls [f ()] and returns its result. If it raises, the
+(** [finally ~h f] calls [f ()] and returns its result. If it raises, the
     same exception is raised; in {b any} case, [h ()] is called after
     [f ()] terminates.
     If [h ()] raises an exception, then this exception will be passed on and

src/core/CCHash.mli

@@ -43,8 +43,8 @@ val if_ : bool -> 'a t -> 'a t -> 'a t
 (** Decide which hash function to use depending on the boolean. *)
 
 val poly : 'a t
-(** The regular polymorphic hash function.
+(** [poly x] is [Hashtbl.hash x].
-    [poly x] is [Hashtbl.hash x]. *)
+    The regular polymorphic hash function. *)
 
 val list_comm : 'a t -> 'a list t
 (** Commutative version of {!list}. Lists that are equal up to permutation