Comment updates

Author: tbkka

stdlib/public/core/FloatingPointToString.swift

@@ -36,7 +36,7 @@
 /// https://doi.org/10.1145/2837614.2837654
 /// In particular, the Errol paper explored the impact of higher-precision
 /// fixed-width arithmetic on Grisu2 and showed a way to rapidly test
-/// the correctness of such algorithms.
+/// the correctness of Grisu-style algorithms.
 ///
 /// A few further improvements were inspired by the Ryu algorithm
 /// from Ulf Anders; "Ryū: fast float-to-string conversion", 2018.
@@ -53,10 +53,12 @@
 ///   values on 32-bit processors, and higher-precision values on all
 ///   processors, it is considerably faster.
 ///
-/// * Always Accurate. Converting the decimal form back to binary
-///   will always yield exactly the same value. For the IEEE 754
-///   formats, the round-trip will produce exactly the same bit
-///   pattern in memory.
+/// * Always Accurate. Except for NaNs, converting the decimal form
+///   back to binary will always yield an equal value. For the IEEE
+///   754 formats, the round trip will produce exactly the same bit
+///   pattern in memory. This assumes, of course, that the conversion
+///   from text to binary uses a correctly-rounded algorithm such as
+///   Clinger 1990 or Eisel-Lemire 2021.
 ///
 /// * Always Short.  This always selects an accurate result with the
 ///   minimum number of significant digits.
@@ -73,12 +75,27 @@
 /// * When present, a '.' is never the first or last character
 /// * There is a consecutive range of integer values that can be
 ///   represented in any particular type (-2^54...2^54 for double).
-///   Never use exponential form for integral numbers in this range.
+///   We do not use exponential form for integral numbers in this
+///   range.
 /// * Generally follow existing practice: Don't use use exponential
 ///   form for fractional values bigger than 10^-4; always write at
 ///   least 2 digits for an exponent.
 /// * Apart from the above, we do prefer shorter output.
 
+/// Note: If you want to compare performance of this implementation
+/// versus some others, keep in mind that this implementation does
+/// deliberately sacrifice some performance.  Any attempt to compare
+/// the performance of this implementation to others should
+/// try to compensate for the following:
+/// * The output ergonomics described above do take some time.
+///   It would be faster to always emit the form "123456e-78"
+//    (See `finishFormatting()`)
+/// * The implementations in published papers generally include
+///   large tables with every power of 10 computed out.  We've
+///   factored these tables down to conserve code size, which
+///   requires some additional work to reconstruct the needed power
+///   of 10. (See the `intervalContainingPowerOf10_*` functions)
+
 ///
 /// This Swift implementation was ported from an earlier C version;
 /// the output is exactly the same in all cases.
@@ -90,7 +107,7 @@
 ///   implementation to ensure that no unsafety actually occurs.  For
 ///   Float32, that testing was exhaustive -- we verified all 4
 ///   billion possible Float32 values.
-/// * The Swift code uses an idiom of building up to 8 ASCII characters
+/// * The Swift code uses an idiom of building up to 8 digit characters
 ///   in a UInt64 and then writing the whole block to memory.
 /// * The Swift version is slightly faster than the C version;
 ///   mostly thanks to various minor algorithmic tweaks that were
@@ -348,6 +365,7 @@ fileprivate func _Float16ToASCII(
                 // Exhaustive testing shows that the only input value
                 // affected by this is 0.015625 == 2^-6, which
                 // incorrectly prints as "0.01562" without this fix.
+                // With this, it prints correctly as "0.01563"
                 if t < lDigit || (t == lDigit && l > 0) {
 	            t += 1
                 }