From fa904a7d3c89c2ad18a426017aeda5bb0d7dd8bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Pottier?=
 <fpottier@users.noreply.github.com>
Date: Fri, 24 Jun 2022 16:37:13 +0200
Subject: [PATCH 06/24] Better documentation for [string_of_float]. (#11353)

Better documentation for [string_of_float] (and [Float.to_string])
with similar warnings for [print_float] and [prerr_float]  in a similar way.

(cherry picked from commit 40113fbc73930b41a7a2df468de18c94feeefdf5)
---
 stdlib/float.mli                    |  7 ++++++-
 stdlib/stdlib.mli                   | 15 ++++++++++++---
 stdlib/templates/float.template.mli |  7 ++++++-
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/stdlib/float.mli b/stdlib/float.mli
index ba84d9b0e2..93d2f3016d 100644
--- a/stdlib/float.mli
+++ b/stdlib/float.mli
@@ -178,7 +178,12 @@ val of_string_opt: string -> float option
 (** Same as [of_string], but returns [None] instead of raising. *)
 
 val to_string : float -> string
-(** Return the string representation of a floating-point number. *)
+(** Return a string representation of a floating-point number.
+
+    This conversion can involve a loss of precision. For greater control over
+    the manner in which the number is printed, see {!Printf}.
+
+    This function is an alias for {!Stdlib.string_of_float}. *)
 
 type fpclass = Stdlib.fpclass =
     FP_normal           (** Normal number, none of the below *)
diff --git a/stdlib/stdlib.mli b/stdlib/stdlib.mli
index 237adfbdd8..0eaee2716e 100644
--- a/stdlib/stdlib.mli
+++ b/stdlib/stdlib.mli
@@ -776,7 +776,10 @@ external int_of_string : string -> int = "caml_int_of_string"
    [Failure "int_of_string"] instead of returning [None]. *)
 
 val string_of_float : float -> string
-(** Return the string representation of a floating-point number. *)
+(** Return a string representation of a floating-point number.
+
+    This conversion can involve a loss of precision. For greater control over
+    the manner in which the number is printed, see {!Printf}. *)
 
 val float_of_string_opt: string -> float option
 (** Convert the given string to a float.  The string is read in decimal
@@ -861,7 +864,10 @@ val print_int : int -> unit
 (** Print an integer, in decimal, on standard output. *)
 
 val print_float : float -> unit
-(** Print a floating-point number, in decimal, on standard output. *)
+(** Print a floating-point number, in decimal, on standard output.
+
+    The conversion of the number to a string uses {!string_of_float} and
+    can involve a loss of precision. *)
 
 val print_endline : string -> unit
 (** Print a string, followed by a newline character, on
@@ -889,7 +895,10 @@ val prerr_int : int -> unit
 (** Print an integer, in decimal, on standard error. *)
 
 val prerr_float : float -> unit
-(** Print a floating-point number, in decimal, on standard error. *)
+(** Print a floating-point number, in decimal, on standard error.
+
+    The conversion of the number to a string uses {!string_of_float} and
+    can involve a loss of precision. *)
 
 val prerr_endline : string -> unit
 (** Print a string, followed by a newline character on standard
diff --git a/stdlib/templates/float.template.mli b/stdlib/templates/float.template.mli
index e35c01809f..e2f7411a02 100644
--- a/stdlib/templates/float.template.mli
+++ b/stdlib/templates/float.template.mli
@@ -178,7 +178,12 @@ val of_string_opt: string -> float option
 (** Same as [of_string], but returns [None] instead of raising. *)
 
 val to_string : float -> string
-(** Return the string representation of a floating-point number. *)
+(** Return a string representation of a floating-point number.
+
+    This conversion can involve a loss of precision. For greater control over
+    the manner in which the number is printed, see {!Printf}.
+
+    This function is an alias for {!Stdlib.string_of_float}. *)
 
 type fpclass = Stdlib.fpclass =
     FP_normal           (** Normal number, none of the below *)
-- 
2.37.0.rc2