Comments presentation

src/core/CCHashtbl.mli

@@ -19,7 +19,9 @@ type 'a printer = Format.formatter -> 'a -> unit
 
 module Poly : sig
   val get : ('a,'b) Hashtbl.t -> 'a -> 'b option
-  (** Safe version of {!Hashtbl.find}. *)
+  (** [get tbl k] finds a binding for the key [k] if present,
+      or returns [None] if no value is found.
+      Safe version of {!Hashtbl.find}. *)
 
   val get_or : ('a,'b) Hashtbl.t -> 'a -> default:'b -> 'b
   (** [get_or tbl k ~default] returns the value associated to [k] if present,
@@ -27,22 +29,22 @@ module Poly : sig
       @since 0.16 *)
 
   val keys : ('a,'b) Hashtbl.t -> 'a iter
-  (** Iterate on keys (similar order as {!Hashtbl.iter}). *)
+  (** [keys tbl f] iterates on keys (similar order as {!Hashtbl.iter}). *)
 
   val values : ('a,'b) Hashtbl.t -> 'b iter
-  (** Iterate on values in the table. *)
+  (** [values tbl f] iterates on values in the table [tbl]. *)
 
   val keys_list : ('a, 'b) Hashtbl.t -> 'a list
-  (** [keys_list t] is the list of keys in [t].
+  (** [keys_list tbl] is the list of keys in [tbl].
       If the key is in the Hashtable multiple times, all occurrences will be returned.
       @since 0.8 *)
 
   val values_list : ('a, 'b) Hashtbl.t -> 'b list
-  (** [values_list t] is the list of values in [t].
+  (** [values_list tbl] is the list of values in [tbl].
       @since 0.8 *)
 
   val map_list : ('a -> 'b -> 'c) -> ('a, 'b) Hashtbl.t -> 'c list
-  (** Map on a hashtable's items, collect into a list. *)
+  (** [map_list f tbl] maps on a [tbl]'s items. Collect into a list. *)
 
   val incr : ?by:int -> ('a, int) Hashtbl.t -> 'a -> unit
   (** [incr ?by tbl x] increments or initializes the counter associated with [x].
@@ -52,7 +54,7 @@ module Poly : sig
       @since 0.16 *)
 
   val decr : ?by:int -> ('a, int) Hashtbl.t -> 'a -> unit
-  (** Like {!incr} but subtract 1 (or the value of [by]).
+  (** [decr ?by tbl x] is like {!incr} but subtract 1 (or the value of [by]).
       If the value reaches 0, the key is removed from the table.
       This does nothing if the key is not already present in the table.
       @since 0.16 *)
@@ -103,10 +105,10 @@ module Poly : sig
       @since 2.8 *)
 
   val to_list : ('a,'b) Hashtbl.t -> ('a * 'b) list
-  (** List of bindings (order unspecified). *)
+  (** [to_list tbl] returns the list of (key,value) bindings (order unspecified). *)
 
   val of_list : ('a * 'b) list -> ('a,'b) Hashtbl.t
-  (** Build a table from the given list of bindings [k_i -> v_i],
+  (** [of_list l] builds a table from the given list [l] of bindings [k_i -> v_i],
       added in order using {!add}. If a key occurs several times,
       it will be added several times, and the visible binding
       will be the last one. *)
@@ -127,7 +129,8 @@ module Poly : sig
       @since 1.0 *)
 
   val pp : 'a printer -> 'b printer -> ('a, 'b) Hashtbl.t printer
-  (** Printer for table.
+  (** [pp pp_k pp_v] returns a table printer given a [pp_k] printer
+      for individual key and a [pp_v] printer for individual value.
       Renamed from [print] since 2.0.
       @since 0.13 *)
 end
@@ -140,7 +143,9 @@ module type S = sig
   include Hashtbl.S
 
   val get : 'a t -> key -> 'a option
-  (** Safe version of {!Hashtbl.find}. *)
+  (** [get tbl k] finds a binding for the key [k] if present,
+      or returns [None] if no value is found.
+      Safe version of {!Hashtbl.find}. *)
 
   val get_or : 'a t -> key -> default:'a -> 'a
   (** [get_or tbl k ~default] returns the value associated to [k] if present,
@@ -160,19 +165,19 @@ module type S = sig
       @since 0.16 *)
 
   val decr : ?by:int -> int t -> key -> unit
-  (** Like {!incr} but subtract 1 (or the value of [by]).
+  (** [decr ?by tbl x] is like {!incr} but subtract 1 (or the value of [by]).
       If the value reaches 0, the key is removed from the table.
       This does nothing if the key is not already present in the table.
       @since 0.16 *)
 
   val keys : 'a t -> key iter
-  (** Iterate on keys (similar order as {!Hashtbl.iter}). *)
+  (**  [keys tbl f] iterates on keys (similar order as {!Hashtbl.iter}). *)
 
   val values : 'a t -> 'a iter
-  (** Iterate on values in the table. *)
+  (**  [values tbl f] iterates on values in the table. *)
 
   val keys_list : _ t -> key list
-  (** [keys_list t] is the list of keys in [t].
+  (** [keys_list tbl] is the list of keys in [tbl].
       If the key is in the Hashtable multiple times, all occurrences will be returned.
       @since 0.8 *)
 
@@ -224,10 +229,10 @@ module type S = sig
       @since 2.8 *)
 
   val to_list : 'a t -> (key * 'a) list
-  (** List of bindings (order unspecified). *)
+  (** [to_list tbl] returns the list of (key,value) bindings (order unspecified). *)
 
   val of_list : (key * 'a) list -> 'a t
-  (** Build a table from the given list of bindings [k_i -> v_i],
+  (** [of_list l] builds a table from the given list [l] of bindings [k_i -> v_i],
       added in order using {!add}. If a key occurs several times,
       it will be added several times, and the visible binding
       will be the last one. *)
@@ -248,7 +253,8 @@ module type S = sig
       @since 1.0 *)
 
   val pp : key printer -> 'a printer -> 'a t printer
-  (** Printer for tables.
+  (** [pp pp_k pp_v] returns a table printer given a [pp_k] printer
+      for individual key and a [pp_v] printer for individual value. 
       Renamed from [print] since 2.0.
       @since 0.13 *)
 end

src/core/CCHeap.mli

@@ -34,63 +34,62 @@ module type S = sig
   type t
 
   val empty : t
-  (** Empty heap. *)
+  (** [empty] returns the empty heap. *)
 
   val is_empty : t -> bool
-  (** Is the heap empty? *)
+  (** [is_empty h] returns [true] if the heap [h] is empty. *)
 
   exception Empty
 
   val merge : t -> t -> t
-  (** Merge two heaps. *)
+  (** [merge h1 h2] merges the two heaps [h1] and [h2]. *)
 
   val insert : elt -> t -> t
-  (** Insert a value in the heap. *)
+  (** [insert x h] inserts an element [x] into the heap [h]. *)
 
   val add : t -> elt -> t
-  (** Synonym to {!insert}. *)
+  (** [add h x] inserts an element [x] into the heap [h]. *)
 
   val filter :  (elt -> bool) -> t -> t
-  (** Filter values, only retaining the ones that satisfy the predicate.
+  (** [filter p h] filters values, only retaining the ones that satisfy the predicate [p].
       Linear time at least. *)
 
   val find_min : t -> elt option
-  (** Find minimal element. *)
+  (** [find_min h] find the minimal element of the heap [h]. *)
 
   val find_min_exn : t -> elt
-  (** Like {!find_min} but can fail.
+  (** [find_min_exn h] is like {!find_min} but can fail.
       @raise Empty if the heap is empty. *)
 
   val take : t -> (t * elt) option
-  (** Extract and return the minimum element, and the new heap (without
+  (** [take h] extracts and returns the minimum element, and the new heap (without
-      this element), or [None] if the heap is empty. *)
+      this element), or [None] if the heap [h] is empty. *)
 
   val take_exn : t -> t * elt
-  (** Like {!take}, but can fail.
+  (** [take_exn h] is like {!take}, but can fail.
       @raise Empty if the heap is empty. *)
 
   val delete_one : (elt -> elt -> bool) -> elt -> t -> t
-  (** Delete one occurrence of a value if it exist in the heap.
+  (** [delete_one eq x h] uses [eq] to find one occurrence of a value [x]
-      [delete_one eq x h], use [eq] to find one [x] in [h] and delete it.
+      if it exist in the heap [h], and delete it.
       If [h] do not contain [x] then it return [h].
       @since 2.0 *)
 
   val delete_all : (elt -> elt -> bool) -> elt -> t -> t
-  (** Delete all occurrences of a value in the heap.
+  (** [delete_all eq x h] uses [eq] to find all [x] in [h] and delete them.
-      [delete_all eq x h], use [eq] to find all [x] in [h] and delete them.
       If [h] do not contain [x] then it return [h].
       The difference with {!filter} is that [delete_all] stops as soon as
       it enters a subtree whose root is bigger than the element.
       @since 2.0 *)
 
   val iter : (elt -> unit) -> t -> unit
-  (** Iterate on elements. *)
+  (** [iter f h] iterates over the heap [h] invoking [f] with the current element. *)
 
   val fold : ('a -> elt -> 'a) -> 'a -> t -> 'a
-  (** Fold on all values. *)
+  (** [fold f acc h] folds on all values of [h]. *)
 
   val size : t -> int
-  (** Number of elements (linear complexity). *)
+  (** [size h] is the number of elements in the heap [h]. Linear complexity. *)
 
   (** {2 Conversions}
 
@@ -99,77 +98,86 @@ module type S = sig
       are now [add_seq], [add_gen], [add_klist]). *)
 
   val to_list : t -> elt list
-  (** Return the elements of the heap, in no particular order. *)
+  (** [to_list h] returns the elements of the heap [h], in no particular order. *)
 
   val to_list_sorted : t -> elt list
-  (** Return the elements in increasing order.
+  (** [to_list_sorted h] returns the elements of the heap [h] in increasing order.
       @since 1.1 *)
 
   val add_list : t -> elt list -> t
-  (** Add the elements of the list to the heap. An element occurring several
+  (** [add_list h l] adds the elements of the list [l] into the heap [h].
-      times will be added that many times to the heap.
+      An element occurring several times will be added that many times to the heap.
       @since 0.16 *)
 
   val of_list : elt list -> t
   (** [of_list l] is [add_list empty l]. Complexity: [O(n log n)]. *)
 
   val add_iter : t -> elt iter -> t
-  (** Like {!add_list}.
+  (** [add_iter h iter] is like {!add_list}.
       @since 2.8 *)
 
   val add_std_seq : t -> elt Seq.t -> t
-  (** Like {!add_list}.
+  (** [add_std_seq h Seq.t] is like {!add_list}.
       @since 2.8 *)
 
   val of_iter : elt iter -> t
-  (** Build a heap from a given [iter]. Complexity: [O(n log n)].
+  (** [of_iter iter] builds a heap from a given [iter]. Complexity: [O(n log n)].
       @since 2.8 *)
 
   val of_std_seq : elt Seq.t -> t
-  (** Build a heap from a given [Seq.t]. Complexity: [O(n log n)].
+  (** [of_std_seq Seq.t] builds a heap from a given [Seq.t]. Complexity: [O(n log n)].
       @since 2.8 *)
 
   val to_iter : t -> elt iter
-  (** Return a [iter] of the elements of the heap.
+  (** [to_iter h] returns a [iter] of the elements of the heap [h].
       @since 2.8 *)
 
   val to_std_seq : t -> elt Seq.t
-  (** Return a [Seq.t] of the elements of the heap.
+  (** [to_std_seq h] returns a [Seq.t] of the elements of the heap [h].
       @since 2.8 *)
 
   val to_iter_sorted : t -> elt iter
-  (** Iterate on the elements, in increasing order.
+  (** [to_iter_sorted h] returns a [iter] by iterating on the elements of [h], 
+      in increasing order.
       @since 2.8 *)
 
   val to_std_seq_sorted : t -> elt Seq.t
-  (** Iterate on the elements, in increasing order.
+  (** [to_std_seq_sorted h ] returns a [Seq.t] by iterating on the elements of [h],
+      in increasing order.
       @since 2.8 *)
 
-  val add_klist : t -> elt klist -> t (** @since 0.16 *)
+  val add_klist : t -> elt klist -> t
+  (** [add_klist h klist] adds the klist [klist] to the heap [h].
+      @since 0.16 *)
 
   val of_klist : elt klist -> t
-  (** Build a heap from a given [klist]. Complexity: [O(n log n)]. *)
+  (** [of_klist klist] builds a heap from a given [klist]. Complexity: [O(n log n)]. *)
 
   val to_klist : t -> elt klist
-  (** Return a [klist] of the elements of the heap. *)
+  (** [to_klist h] returns a [klist] of the elements of the heap [h]. *)
 
-  val add_gen : t -> elt gen -> t (** @since 0.16 *)
+  val add_gen : t -> elt gen -> t
+  (** [add_gen h gen] adds the gen [gen] to the heap [h].
+      @since 0.16 *)
 
   val of_gen : elt gen -> t
-  (** Build a heap from a given [gen]. Complexity: [O(n log n)]. *)
+  (** [of_gen gen] builds a heap from a given [gen]. Complexity: [O(n log n)]. *)
 
   val to_gen : t -> elt gen
-  (** Return a [gen] of the elements of the heap. *)
+  (** [to_gen h] returns a [gen] of the elements of the heap [h]. *)
 
   val to_tree : t -> elt ktree
-  (** Return a [ktree] of the elements of the heap. *)
+  (** [to_tree h] returns a [ktree] of the elements of the heap [h]. *)
 
   val to_string : ?sep:string -> (elt -> string) -> t -> string
-  (**  Print the heap in a string
+  (**  [to_string ?sep f h] prints the heap [h] in a string
+       using [sep] as a given separator (default ",") between each element
+       (converted to a string using [f]).
        @since 2.7 *)
 
   val pp : ?sep:string -> elt printer -> t printer
-  (** Printer.
+  (** [pp ?sep ppf h] prints [h] on [ppf].
+      Elements are separated by [sep] (default ",").
       Renamed from {!print} since 2.0
       @since 0.16 *)
 end

src/core/CCInt.mli

@@ -6,33 +6,37 @@
 type t = int
 
 val compare : t -> t -> int
-(** The comparison function for integers with the same specification as {!Stdlib.compare}. *)
+(** [compare x y] is the comparison function for integers 
+    with the same specification as {!Stdlib.compare}. *)
 
 val equal : t -> t -> bool
-(** Equality function for integers. *)
+(** [equal x y] is [true] iff [x] and [y] are equal.
+    Equality function for integers. *)
 
 val hash : t -> int
+(** [hash x] computes the hash of [x]. *)
   
 val sign : t -> int
-(** [sign i] is one of [-1, 0, 1]. *)
+(** [sign x] is one of [-1, 0, 1]. *)
 
 val neg : t -> t
-(** Unary negation. [neg i = - i].
+(** [neg x] is [- x].
+    Unary negation.
     @since 0.5 *)
 
 val pow : t -> t -> t
 (** [pow base exponent] returns [base] raised to the power of [exponent].
-    [pow a b = a^b] for positive integers [a] and [b].
+    [pow x y = x^y] for positive integers [x] and [y].
-    Raises [Invalid_argument] if [a = b = 0] or [b] < 0.
+    Raises [Invalid_argument] if [x = y = 0] or [y] < 0.
     @since 0.11 *)
 
 val floor_div : t -> t -> t
-(** [floor_div a n] is integer division rounding towards negative infinity.
+(** [floor_div x n] is integer division rounding towards negative infinity.
-    It satisfies [a = m * floor_div a n + rem a n].
+    It satisfies [x = m * floor_div x n + rem x n].
     @since 1.2 *)
 
 val rem : t -> t -> t
-(** [rem a n] is the remainder of dividing [a] by [n], with the same
+(** [rem x n] is the remainder of dividing [x] by [n], with the same
     sign as [n].
     @since 1.2 *)
 
@@ -45,36 +49,43 @@ val random_small : t random_gen
 val random_range : int -> int -> t random_gen
 
 val pp : t printer
+(** [pp ppf x] prints the integer [x] on [ppf]. *)    
 
 val to_string : t -> string
-(** Return the string representation of its argument, in signed decimal.
+(** [to_string x] returns the string representation of the integer [x], in signed decimal.
     @since 0.13 *)
 
 val of_string : string -> t option
-(** @since 0.13 *)
+(** [of_string s] converts the given string [s] into an integer.
+    Safe version of {!of_string_exn}.
+    @since 0.13 *)
 
 val of_string_exn : string -> t
-(** Alias to {!int_of_string}.
+(** [of_string_exn s] converts the given string [s] to an integer.
+    Alias to {!int_of_string}.
     @raise Failure in case of failure.
     @since NEXT_RELEASE *)
 
 val of_float : float -> t
-(** Alias to {!int_of_float}.
+(** [of_float x] converts the given floating-point number [x] to an integer.
+    Alias to {!int_of_float}.
     @since NEXT_RELEASE *)
 
 val pp_binary : t printer
-(** Print as "0b00101010".
+(** [pp_binary ppf x] prints [x] on [ppf].
+    Print as "0b00101010".
     @since 0.20 *)
 
 val to_string_binary : t -> string
-(** @since 0.20 *)
+(** [to_string_binary x] returns the string representation of the integer [x], in binary.
+    @since 0.20 *)
 
 val min : t -> t -> t
-(** The minimum of two integers.
+(** [min x y] returns the minimum of the two integers [x] and [y].
     @since 0.17 *)
 
 val max : t -> t -> t
-(** The maximum of two integers.
+(** [max x y] returns the maximum of the two integers [x] and [y].
     @since 0.17 *)
 
 val range_by : step:t -> t -> t -> t iter
@@ -90,7 +101,7 @@ val range : t -> t -> t iter
     @since 1.2 *)
 
 val range' : t -> t -> t iter
-(** Like {!range} but the second bound is excluded.
+(** [range' i j] is like {!range} but the second bound [j] is excluded.
     For instance [range' 0 5 = Iter.of_list [0;1;2;3;4]].
     @since 1.2 *)
 

src/core/CCInt32.mli

@@ -18,39 +18,44 @@
 include module type of struct include Int32 end
 
 val ( + ) : t -> t -> t
-(** Addition. *)
+(** [x + y] is the sum of [x] and [y]. 
+    Addition. *)
 
 val ( - ) : t -> t -> t
-(** Subtraction. *)
+(** [x - y] is the difference of [x] and [y].
+    Subtraction. *)
 
 val ( ~- ) : t -> t
-(** Unary negation. *)
+(** [~- x] is the negation of [x].
+    Unary negation. *)
 
 val ( * ) : t -> t -> t
-(** Multiplication. *)
+(** [ x * y] is the product of [x] and [y].
+    Multiplication. *)
 
 val ( / ) : t -> t -> t
-(** Integer division.  Raise [Division_by_zero] if the second
+(** [x / y] is the integer quotient of [x] and [y].
-    argument is zero.  This division rounds the real quotient of
+    Integer division.  Raise [Division_by_zero] if the second
+    argument [y] is zero.  This division rounds the real quotient of
     its arguments towards zero, as specified for {!Stdlib.(/)}. *)
 
 val ( mod ) : t -> t -> t
-(** [x mod y ] is the integer remainder.
+(** [x mod y] is the integer remainder of [x / y].
     If [y <> zero], the result of [x mod y] satisfies the following property:
     [x = ((x / y) * y) + (x mod y)].
     If [y = 0], [x mod y] raises [Division_by_zero]. *)
 
 val ( land ) : t -> t -> t
-(** Bitwise logical and. *)
+(** [x land y] is the bitwise logical and of [x] and [y]. *)
 
 val ( lor ) : t -> t -> t
-(** Bitwise logical or. *)
+(** [x lor y] is the bitwise logical or of [x] and [y]. *)
 
 val ( lxor ) : t -> t -> t
-(** Bitwise logical exclusive or. *)
+(** [x lxor y] is the bitwise logical exclusive or of [x] and [y]. *)
 
 val lnot : t -> t
-(** Bitwise logical negation. *)
+(** [lnot x] is the bitwise logical negation of [x] (the bits of [x] are inverted). *)
 
 val ( lsl ) : t -> int -> t
 (** [ x lsl y] shifts [x] to the left by [y] bits, filling in with zeroes.
@@ -93,35 +98,39 @@ end
 include module type of Infix
 
 val hash : t -> int
-(** Like {!Stdlib.abs (to_int x)}. *)
+(** [hash x] computes the hash of [x].
+    Like {!Stdlib.abs (to_int x)}. *)
 
 (** {2 Conversion} *)
 
 val to_int : t -> int
-(** Convert the given 32-bit integer (type [int32]) to an
+(** [to_int x] converts the given 32-bit integer [x] (type [int32]) into an
     integer (type [int]). On 32-bit platforms, the 32-bit integer
     is taken modulo 2{^31}, i.e. the high-order bit is lost
     during the conversion. On 64-bit platforms, the conversion is exact. *)
 
 val of_int : int -> t
-(** Alias to {!Int32.of_int}. *)
+(** [of_int x] converts the given integer [x] (type [int]) into an
+    32-bit integer (type [int32]).
+    Alias to {!Int32.of_int}. *)
 
 val to_float : t -> float
-(** Convert the given 32-bit integer to a floating-point number. *)
+(** [to_float x] converts the given 32-bit integer [x] 
+    into a floating-point number (type [float]). *)
 
 val of_float : float -> t
-(** Alias to {!Int32.of_float}.
+(** [of_float x] converts the given floating-point number [x] into a 32-bit integer,
-    Convert the given floating-point number to a 32-bit integer,
     discarding the fractional part (truncate towards 0).
     The result of the conversion is undefined if, after truncation, the number
-    is outside the range \[{!CCInt32.min_int}, {!CCInt32.max_int}\]. *)
+    is outside the range \[{!CCInt32.min_int}, {!CCInt32.max_int}\]. 
+    Alias to {!Int32.of_float}. *)
 
 val to_string : t -> string
-(** Return the string representation of its argument, in signed decimal. *)
+(** [to_string x] returns the string representation of its argument [x], in signed decimal. *)
 
 val of_string_exn : string -> t
-(** Alias to {!Int32.of_string}.
+(** [of_string_exn s] converts the given string [s] into a 32-bit integer.
-    Convert the given string to a 32-bit integer.
+    Alias to {!Int32.of_string}.
     The string is read in decimal (by default, or if the string
     begins with [0u]) or in hexadecimal, octal or binary if the
     string begins with [0x], [0o] or [0b] respectively.
@@ -138,8 +147,8 @@ val of_string_exn : string -> t
     exceeds the range of integers representable in type [int32]. *)
 
 val of_string : string -> t option
-(** Safe version of {!of_string_exn}.
+(** [of_string s] is the safe version of {!of_string_exn}.
     Like {!of_string_exn}, but return [None] instead of raising. *)
 
 val of_string_opt : string -> t option
-(** Alias to {!of_string}. *)
+(** [of_string_opt s] is an alias to {!of_string}. *)

src/core/CCInt64.mli

@@ -9,46 +9,53 @@
 include module type of struct include Int64 end
 
 val ( + ) : t -> t -> t
-(** Addition. *)
+(** [x + y] is the sum of [x] and [y]. 
+    Addition. *)
 
 val ( - ) : t -> t -> t
-(** Subtraction. *)
+(** [x - y] is the difference of [x] and [y].
+    Subtraction. *)
 
 val ( ~- ) : t -> t
-(** Unary negation. *)
+(** [~- x] is the negation of [x].
+    Unary negation. *)
 
 val ( * ) : t -> t -> t
-(** Multiplication. *)
+(** [ x * y] is the product of [x] and [y].
+    Multiplication. *)
 
 val ( / ) : t -> t -> t
-(** Integer division.  Raise [Division_by_zero] if the second
+(** [x / y] is the integer quotient of [x] and [y].
-    argument is zero.  This division rounds the real quotient of
+    Integer division.  Raise [Division_by_zero] if the second
+    argument [y] is zero.  This division rounds the real quotient of
     its arguments towards zero, as specified for {!Stdlib.(/)}. *)
 
 val ( mod ) : t -> t -> t
-(** Integer remainder.
+(** [x mod y] is the integer remainder of [x / y].
+    If [y <> zero], the result of [x mod y] satisfies the following property:
+    [x = ((x / y) * y) + (x mod y)].
     If [y = 0], [x mod y] raises [Division_by_zero]. *)
 
 val abs : t -> t
-(** Return the absolute value of its argument. *)
+(** [abs x] returns the absolute value (or magnitude) of its argument [x]. *)
 
 val max_int : t
-(** The greatest representable 64-bit integer, 2{^63} - 1 = [9_223_372_036_854_775_807]. *)
+(** [max_int] is the greatest representable 64-bit integer, 2{^63} - 1 = [9_223_372_036_854_775_807]. *)
 
 val min_int : t
-(** The smallest representable 64-bit integer, -2{^63} = [-9_223_372_036_854_775_808]. *)
+(** [min_int] is the smallest representable 64-bit integer, -2{^63} = [-9_223_372_036_854_775_808]. *)
 
 val ( land ) : t -> t -> t
-(** Bitwise logical and. *)
+(** [x land y] is the bitwise logical and of [x] and [y]. *)
 
 val ( lor ) : t -> t -> t
-(** Bitwise logical or. *)
+(** [x lor y] is the bitwise logical or of [x] and [y]. *)
 
 val ( lxor ) : t -> t -> t
-(** Bitwise logical exclusive or. *)
+(** [x lxor y] is the bitwise logical exclusive or of [x] and [y]. *)
 
 val lnot : t -> t
-(** Bitwise logical negation. *)
+(** [lnot x] is the bitwise logical negation of [x] (the bits of [x] are inverted). *)
 
 val ( lsl ) : t -> int -> t
 (** [ x lsl y] shifts [x] to the left by [y] bits, filling in with zeroes.
@@ -93,18 +100,19 @@ end
 include module type of Infix
 
 val compare : t -> t -> int
-(** The comparison function for 64-bit integers, with the same specification as
+(** [compare x y] is the comparison function for 64-bit integers, with the same specification as
     {!Stdlib.compare}.  Along with the type [t], this function [compare]
     allows the module [CCInt64] to be passed as argument to the functors
     {!Set.Make} and {!Map.Make}. *)
 
 val hash : t -> int
-(** Like {!Stdlib.abs (to_int x)}. *)
+(** [hash x] computes the hash of [x].
+    Like {!Stdlib.abs (to_int x)}. *)
   
 (** {2 Conversion} *)
 
 val to_int : t -> int
-(** Convert the given 64-bit integer (type [int64]) to an
+(** [to_int x] converts the given 64-bit integer [x] (type [int64]) into an
     integer (type [int]).  On 64-bit platforms, the 64-bit integer
     is taken modulo 2{^63}, i.e. the high-order bit is lost
     during the conversion.  On 32-bit platforms, the 64-bit integer
@@ -112,53 +120,59 @@ val to_int : t -> int
     during the conversion. *)
 
 val of_int : int -> t
-(** Alias to {!Int64.of_int}.
+(** [of_int x] converts the given integer [x] (type [int]) into an
+    64-bit integer (type [int64]).
+    Alias to {!Int64.of_int}.
     NOTE: used to return an option, but the function actually never fails. *)
 
 val to_int32 : t -> int32
-(** Convert the given 64-bit integer (type [int64]) to a
+(** [to_int32 x] converts the given 64-bit integer [x] (type [int64]) to a
     32-bit integer (type [int32]). The 64-bit integer
     is taken modulo 2{^32}, i.e. the top 32 bits are lost
     during the conversion.  *)
 
 val of_int32 : int32 -> t
-(** Alias to {!Int64.of_int32}.
+(** [of_int32 x] converts the given 32-bit integer [x] (type [int32]) into an
+    64-bit integer (type [int64]).
+    Alias to {!Int64.of_int32}.
     NOTE: use to return an option, but the function actually never fails. *)
 
 val to_nativeint : t -> nativeint
-(** Convert the given 64-bit integer (type [int64]) to a
+(** [to_nativeint x] converts the given 64-bit integer [x] (type [int64]) into a
     native integer.  On 32-bit platforms, the 64-bit integer
     is taken modulo 2{^32}.  On 64-bit platforms,
     the conversion is exact. *)
 
 val of_nativeint : nativeint -> t
-(** Alias to {!Int64.of_nativeint}.
+(** [of_nativeint x] converts the given nativeint integer [x] (type [nativeint]) into an
+    64-bit integer (type [int64]).
+    Alias to {!Int64.of_nativeint}.
     NOTE: use to return an option, but the function actually never fails. *)
 
 val to_float : t -> float
-(** Convert the given 64-bit integer to a floating-point number. *)
+(** [to_float x] converts the given 64-bit integer [x] into a floating-point number. *)
 
 val of_float : float -> t
-(** Alias to {!Int64.of_float}.
+(** [of_float x] converts the given floating-point number [x] into a 64-bit integer,
-    Convert the given floating-point number to a 64-bit integer,
     discarding the fractional part (truncate towards 0).
     The result of the conversion is undefined if, after truncation,
     the number is outside the range \[{!CCInt64.min_int}, {!CCInt64.max_int}\].
+    Alias to {!Int64.of_float}.
     NOTE: used to return an option, but the function never fails. *)
 
 val to_string : t -> string
-(** Return the string representation of its argument, in decimal. *)
+(** [to_string x] returns the string representation of its argument [x], in decimal. *)
 
 val of_string : string -> t option
-(** Safe version of {!of_string_exn}. *)
+(** [of_string s] is the safe version of {!of_string_exn}. *)
 
 val of_string_opt : string -> t option
-(** Alias to {!of_string}.
+(** [of_string_opt s] is an alias to {!of_string}.
     @since 2.1 *)
 
 val of_string_exn : string -> t
-(** Alias to {!Int64.of_string}.
+(** [of_string_exn s] converts the given string [s] into a 64-bit integer.
-    Convert the given string to a 64-bit integer.
+    Alias to {!Int64.of_string}.
     The string is read in decimal (by default, or if the string
     begins with [0u]) or in hexadecimal, octal or binary if the
     string begins with [0x], [0o] or [0b] respectively.