improve float loosely docs

1 files changed, 18 insertions, 3 deletions

diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index dd6adee..ad9acf6 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -67,7 +67,8 @@ pub fn clamp(x: Float, min min_bound: Float, max max_bound: Float) -> Float {
   |> max(min_bound)
 }
 
-/// Compares two `Float`s, returning an order.
+/// Compares two `Float`s, returning an `Order`:
+/// `Lt` for lower than, `Eq` for equals, or `Gt` for greater than.
 ///
 /// ## Examples
 ///
@@ -76,6 +77,10 @@ pub fn clamp(x: Float, min min_bound: Float, max max_bound: Float) -> Float {
 /// Lt
 /// ```
 ///
+/// To handle
+/// [Floating Point Imprecision](https://en.wikipedia.org/wiki/Floating-point_arithmetic#Accuracy_problems)
+/// you may use [`loosely_compare`](#loosely_compare) instead.
+///
 pub fn compare(a: Float, with b: Float) -> Order {
   case a == b {
     True -> order.Eq
@@ -87,9 +92,12 @@ pub fn compare(a: Float, with b: Float) -> Order {
   }
 }
 
-/// Compares two `Float`s within a tolerance and returns an `Order`:
+/// Compares two `Float`s within a tolerance, returning an `Order`:
 /// `Lt` for lower than, `Eq` for equals, or `Gt` for greater than.
 ///
+/// This function allows Float comparison despite
+/// [Floating Point Imprecision](https://en.wikipedia.org/wiki/Floating-point_arithmetic#Accuracy_problems).
+///
 /// Notice: For `Float`s the tolerance won't be exact:
 /// `5.3 - 5.0` is not exactly `0.3`.
 ///
@@ -100,6 +108,9 @@ pub fn compare(a: Float, with b: Float) -> Order {
 /// Eq
 /// ```
 ///
+/// If you want to check only for equality you may use
+/// [`loosely_equals`](#loosely_equals) instead.
+///
 pub fn loosely_compare(
   a: Float,
   with b: Float,
@@ -112,7 +123,11 @@ pub fn loosely_compare(
   }
 }
 
-/// Checks for equality of two `Float`s within a tolerance.
+/// Checks for equality of two `Float`s within a tolerance,
+/// returning an `Bool`.
+///
+/// This function allows Float comparison despite
+/// [Floating Point Imprecision](https://en.wikipedia.org/wiki/Floating-point_arithmetic#Accuracy_problems).
 ///
 /// Notice: For `Float`s the tolerance won't be exact:
 /// `5.3 - 5.0` is not exactly `0.3`.