From 52f6e13db362fb5b7570e7cd5a0298910c66ff59 Mon Sep 17 00:00:00 2001
From: Israel-4Ever <israel@idf.il>
Date: Thu, 23 Mar 2023 16:18:11 -0700
Subject: [PATCH] Document the floating-point numbers spec (#708)

See sass/sass#2892
---
 source/documentation/modules/math.html.md.erb | 69 +++++++++++++++++--
 .../documentation/values/numbers.html.md.erb  |  5 +-
 2 files changed, 68 insertions(+), 6 deletions(-)

diff --git a/source/documentation/modules/math.html.md.erb b/source/documentation/modules/math.html.md.erb
index 9777fa4fd..66fd41425 100644
--- a/source/documentation/modules/math.html.md.erb
+++ b/source/documentation/modules/math.html.md.erb
@@ -9,14 +9,75 @@ title: sass:math
 <% function 'math.$e' do %>
   <% impl_status dart: '1.25.0', libsass: false, ruby: false %>
 
-  Equal to the value of the [mathematical constant *e*][].
+  The closest 64-bit floating point approximation of the [mathematical constant
+  *e*][].
 
   [mathematical constant *e*]: https://en.wikipedia.org/wiki/E_(mathematical_constant)
 
   <% example(autogen_css: false) do %>
     @debug math.$e; // 2.7182818285
     ===
-    @debug math.$e // 2.7182818285
+    @debug math.$e  // 2.7182818285
+  <% end %>
+<% end %>
+
+
+<% function 'math.$epsilon' do %>
+  <% impl_status dart: '1.55.0', libsass: false, ruby: false %>
+
+  The difference between 1 and the smallest 64-bit floating point number greater
+  than 1 according to floating-point comparisons. Because of Sass numbers' [10
+  digits of precision](../values/numbers), in many cases this will appear to
+  be 0.
+<% end %>
+
+<% function 'math.$max-number' do %>
+  <% impl_status dart: '1.55.0', libsass: false, ruby: false %>
+
+  The maximum finite number that can be represented as a 64-bit floating point
+  number.
+
+  <% example(autogen_css: false) do %>
+    @debug math.$max-number; // 179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+    ===
+    @debug math.$max-number  // 179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+  <% end %>
+<% end %>
+
+
+<% function 'math.$max-safe-integer' do %>
+  <% impl_status dart: '1.55.0', libsass: false, ruby: false %>
+
+  The maximum integer `n` such that both `n` and `n + 1` can be precisely
+  represented as a 64-bit floating-point number.
+
+  <% example(autogen_css: false) do %>
+    @debug math.$max-safe-integer; // 9007199254740991
+    ===
+    @debug math.$max-safe-integer  // 9007199254740991
+  <% end %>
+<% end %>
+
+
+<% function 'math.$min-number' do %>
+  <% impl_status dart: '1.55.0', libsass: false, ruby: false %>
+
+  The smallest positive number that can be represented as a 64-bit floating
+  point number. Because of Sass numbers' [10 digits of
+  precision](../values/numbers), in many cases this will appear to be 0.
+<% end %>
+
+
+<% function 'math.$min-safe-integer' do %>
+  <% impl_status dart: '1.55.0', libsass: false, ruby: false %>
+
+  The minimum integer `n` such that both `n` and `n - 1` can be precisely
+  represented as a 64-bit floating-point number.
+
+  <% example(autogen_css: false) do %>
+    @debug math.$min-safe-integer; // -9007199254740991
+    ===
+    @debug math.$min-safe-integer  // -9007199254740991
   <% end %>
 <% end %>
 
@@ -24,14 +85,14 @@ title: sass:math
 <% function 'math.$pi' do %>
   <% impl_status dart: '1.25.0', libsass: false, ruby: false %>
 
-  Equal to the value of the [mathematical constant *π*][].
+  The closest 64-bit floating point approximation of the [mathematical constant *π*][].
 
   [mathematical constant *π*]: https://en.wikipedia.org/wiki/Pi
 
   <% example(autogen_css: false) do %>
     @debug math.$pi; // 3.1415926536
     ===
-    @debug math.$pi // 3.1415926536
+    @debug math.$pi  // 3.1415926536
   <% end %>
 <% end %>
 
diff --git a/source/documentation/values/numbers.html.md.erb b/source/documentation/values/numbers.html.md.erb
index 48893e44b..81c3f13e5 100644
--- a/source/documentation/values/numbers.html.md.erb
+++ b/source/documentation/values/numbers.html.md.erb
@@ -51,8 +51,9 @@ been spotty, Sass always compiles it to fully expanded numbers.
   forwards-compatibility.
 <% end %>
 
-Sass numbers support up to 10 digits of precision after the decimal point. This
-means a few different things:
+Sass numbers are represented internally as 64-bit floating point values. They
+support up to 10 digits of precision after the decimal point when serialized to
+CSS and for the purposes of equality. This means a few different things:
 
 * Only the first ten digits of a number after the decimal point will be included
   in the generated CSS.