[Kernel] Add comments in field.ml

src/libraries/arithmetic/field.ml

@@ -20,6 +20,16 @@
 (*                                                                        *)
 (**************************************************************************)
 
+(** This module provides a generic signature describing mathematical fields,
+    i.e algebraic structure that behave like rationals, reals or complex
+    numbers. The signature also provides several functions that are not
+    directly part of fields definition, but are useful nonetheless, in
+    particular when using fields to model floating point computations.
+    @since Frama-C+dev *)
+
+(** This type is used to return bounds for mathematical functions that
+    cannot be exactly computed using rationals, like the square root
+    for instance. *)
 type 't bounds = { lower : 't ; upper : 't }
 
 module type S = sig
@@ -27,31 +37,43 @@ module type S = sig
   include Datatype.S_with_collections
   type scalar = t
 
+  (** Useful constants in the field. Two is provided for users that model
+      floating point computations using abstractions over the field. *)
   val zero    : scalar
   val one     : scalar
   val two     : scalar
   val pos_inf : scalar
   val neg_inf : scalar
 
+  (** Constructors interacting with standard OCaml types. *)
   val of_int    : int -> scalar
   val of_float  : float -> scalar
   val to_float  : scalar -> float
   val of_string : string -> scalar
 
+  (** Standard arithmetic unary operations. *)
   val neg : scalar -> scalar
   val abs : scalar -> scalar
-  val max : scalar -> scalar -> scalar
-  val min : scalar -> scalar -> scalar
-
-  val pow2 : int -> scalar
-  val log2 : scalar -> int bounds
-  val sqrt : scalar -> scalar bounds
 
+  (** Standard arithmetic binary operations. *)
   val ( + ) : scalar -> scalar -> scalar
   val ( - ) : scalar -> scalar -> scalar
   val ( * ) : scalar -> scalar -> scalar
   val ( / ) : scalar -> scalar -> scalar
 
+  (** [pow2 e] computes the scalar [2 ^ e]. *)
+  val pow2 : int -> scalar
+
+  (** [log2 f] computes the integer [l] and [u] such as
+      [l = floor(log₂ f)] and [u = ceiling(log₂ f)]. *)
+  val log2 : scalar -> int bounds
+
+  (** [sqrt f] computes bounds of the square root of [f]. *)
+  val sqrt : scalar -> scalar bounds
+
+  val max : scalar -> scalar -> scalar
+  val min : scalar -> scalar -> scalar
+
   val ( =  ) : scalar -> scalar -> bool
   val ( != ) : scalar -> scalar -> bool
   val ( <= ) : scalar -> scalar -> bool