From dc548da2e346f98cb7fc3564a7239679e4bdf1a4 Mon Sep 17 00:00:00 2001 From: JPR Date: Mon, 16 Mar 2020 21:22:51 +0100 Subject: [PATCH] Modifs comments --- src/core/CCArray.mli | 3 ++- src/core/CCArrayLabels.mli | 3 ++- src/core/CCBool.mli | 3 ++- src/core/CCChar.mli | 2 +- src/core/CCFloat.mli | 28 ++++++++++++++++------------ src/core/CCFormat.mli | 2 +- src/core/CCFun.mli | 18 +++++++++--------- src/core/CCHash.mli | 4 ++-- 8 files changed, 35 insertions(+), 28 deletions(-) diff --git a/src/core/CCArray.mli b/src/core/CCArray.mli index 34e4007c..bdbb842c 100644 --- a/src/core/CCArray.mli +++ b/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 diff --git a/src/core/CCArrayLabels.mli b/src/core/CCArrayLabels.mli index 40317052..c880fd3c 100644 --- a/src/core/CCArrayLabels.mli +++ b/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 diff --git a/src/core/CCBool.mli b/src/core/CCBool.mli index ea4ad095..f38e85db 100644 --- a/src/core/CCBool.mli +++ b/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]. diff --git a/src/core/CCChar.mli b/src/core/CCChar.mli index 6e604605..959959d1 100644 --- a/src/core/CCChar.mli +++ b/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 diff --git a/src/core/CCFloat.mli b/src/core/CCFloat.mli index c3b2e532..7556a579 100644 --- a/src/core/CCFloat.mli +++ b/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} diff --git a/src/core/CCFormat.mli b/src/core/CCFormat.mli index f4a0198f..d7925f8e 100644 --- a/src/core/CCFormat.mli +++ b/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. diff --git a/src/core/CCFun.mli b/src/core/CCFun.mli index e5f72f69..e9707d81 100644 --- a/src/core/CCFun.mli +++ b/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 diff --git a/src/core/CCHash.mli b/src/core/CCHash.mli index e17743a4..b77d182a 100644 --- a/src/core/CCHash.mli +++ b/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