core: fixed typos and revised comments in flt2dec.

4 files changed, 18 insertions, 15 deletions

diff --git a/src/libcore/num/flt2dec/bignum.rs b/src/libcore/num/flt2dec/bignum.rs
index 449d080dc5c..d6a5e44a1fb 100644
--- a/src/libcore/num/flt2dec/bignum.rs
+++ b/src/libcore/num/flt2dec/bignum.rs
@@ -88,7 +88,7 @@ impl_full_ops! {
     u8:  add(intrinsics::u8_add_with_overflow),  mul/div(u16);
     u16: add(intrinsics::u16_add_with_overflow), mul/div(u32);
     u32: add(intrinsics::u32_add_with_overflow), mul/div(u64);
-//  u64: add(intrinsics::u64_add_with_overflow), mul/div(u128); // damn!
+//  u64: add(intrinsics::u64_add_with_overflow), mul/div(u128); // see RFC #521 for enabling this.
 }
 
 macro_rules! define_bignum {
@@ -103,11 +103,12 @@ macro_rules! define_bignum {
         /// All operations available to bignums panic in the case of over/underflows.
         /// The caller is responsible to use large enough bignum types.
         pub struct $name {
-            /// One plus the offset to the maximum "digit" in the use.
+            /// One plus the offset to the maximum "digit" in use.
             /// This does not decrease, so be aware of the computation order.
             /// `base[size..]` should be zero.
             size: usize,
-            /// Digits. `[a, b, c, ...]` represents `a + b*n + c*n^2 + ...`.
+            /// Digits. `[a, b, c, ...]` represents `a + b*2^W + c*2^(2W) + ...`
+            /// where `W` is the number of bits in the digit type.
             base: [$ty; $n]
         }
 
@@ -215,7 +216,7 @@ macro_rules! define_bignum {
                     self.base[i] = 0;
                 }
 
-                // shift by `nbits` bits
+                // shift by `bits` bits
                 let mut sz = self.size + digits;
                 if bits > 0 {
                     let last = sz;
@@ -236,8 +237,9 @@ macro_rules! define_bignum {
                 self
             }
 
-            /// Multiplies itself by a number described by `other[0] + other[1] * n +
-            /// other[2] * n^2 + ...` and returns its own mutable reference.
+            /// Multiplies itself by a number described by `other[0] + other[1] * 2^W +
+            /// other[2] * 2^(2W) + ...` (where `W` is the number of bits in the digit type)
+            /// and returns its own mutable reference.
             pub fn mul_digits<'a>(&'a mut self, other: &[$ty]) -> &'a mut $name {
                 // the internal routine. works best when aa.len() <= bb.len().
                 fn mul_inner(ret: &mut [$ty; $n], aa: &[$ty], bb: &[$ty]) -> usize {
diff --git a/src/libcore/num/flt2dec/estimator.rs b/src/libcore/num/flt2dec/estimator.rs
index d3e06e406db..d42e05a91f1 100644
--- a/src/libcore/num/flt2dec/estimator.rs
+++ b/src/libcore/num/flt2dec/estimator.rs
@@ -18,6 +18,8 @@
 pub fn estimate_scaling_factor(mant: u64, exp: i16) -> i16 {
     // 2^(nbits-1) < mant <= 2^nbits if mant > 0
     let nbits = 64 - (mant - 1).leading_zeros() as i64;
+    // 1292913986 = floor(2^32 * log_10 2)
+    // therefore this always underestimates (or is exact), but not much.
     (((nbits + exp as i64) * 1292913986) >> 32) as i16
 }
 
diff --git a/src/libcore/num/flt2dec/mod.rs b/src/libcore/num/flt2dec/mod.rs
index 74b190085b3..f51dcf54a19 100644
--- a/src/libcore/num/flt2dec/mod.rs
+++ b/src/libcore/num/flt2dec/mod.rs
@@ -93,7 +93,7 @@ Both implementations expose two public functions:
 
 They try to fill the `u8` buffer with digits and returns the number of digits
 written and the exponent `k`. They are total for all finite `f32` and `f64`
-inputs (Grisu internally falls back to Dragon if possible).
+inputs (Grisu internally falls back to Dragon if necessary).
 
 The rendered digits are formatted into the actual string form with
 four functions:
@@ -114,8 +114,8 @@ four functions:
 They all return a slice of preallocated `Part` array, which corresponds to
 the individual part of strings: a fixed string, a part of rendered digits,
 a number of zeroes or a small (`u16`) number. The caller is expected to
-provide an enough buffer and `Part` array, and to assemble the final
-string from parts itself.
+provide a large enough buffer and `Part` array, and to assemble the final
+string from resulting `Part`s itself.
 
 All algorithms and formatting functions are accompanied by extensive tests
 in `coretest::num::flt2dec` module. It also shows how to use individual
@@ -274,7 +274,7 @@ fn digits_to_dec_str<'a>(buf: &'a [u8], exp: i16, frac_digits: usize,
 
     // if there is the restriction on the last digit position, `buf` is assumed to be
     // left-padded with the virtual zeroes. the number of virtual zeroes, `nzeroes`,
-    // equals to `max(0, exp + frag_digits - buf.len())`, so that the position of
+    // equals to `max(0, exp + frac_digits - buf.len())`, so that the position of
     // the last digit `exp - buf.len() - nzeroes` is no more than `-frac_digits`:
     //
     //                       |<-virtual->|
@@ -373,7 +373,7 @@ pub enum Sign {
     /// Prints `-` only for the negative non-zero values.
     Minus,        // -inf -1  0  0  1  inf nan
     /// Prints `-` only for any negative values (including the negative zero).
-    MinusRaw,     // -inf -1  0  0  1  inf nan
+    MinusRaw,     // -inf -1 -0  0  1  inf nan
     /// Prints `-` for the negative non-zero values, or `+` otherwise.
     MinusPlus,    // -inf -1 +0 +0 +1 +inf nan
     /// Prints `-` for any negative values (including the negative zero), or `+` otherwise.
@@ -639,9 +639,8 @@ pub fn to_exact_fixed_str<'a, T, F>(mut format_exact: F, v: T,
             let limit = if frac_digits < 0x8000 { -(frac_digits as i16) } else { i16::MIN };
             let (len, exp) = format_exact(decoded, &mut buf[..maxlen], limit);
             if exp <= limit {
-                // `format_exact` always returns at least one digit even though the restriction
-                // hasn't been met, so we catch this condition and treats as like zeroes.
-                // this does not include the case that the restriction has been met
+                // the restriction couldn't been met, so this should render like zero no matter
+                // `exp` was. this does not include the case that the restriction has been met
                 // only after the final rounding-up; it's a regular case with `exp = limit + 1`.
                 debug_assert_eq!(len, 0);
                 if frac_digits > 0 { // [0.][0000]
diff --git a/src/libcoretest/num/flt2dec/strategy/grisu.rs b/src/libcoretest/num/flt2dec/strategy/grisu.rs
index ff282ea507c..3d798c8726c 100644
--- a/src/libcoretest/num/flt2dec/strategy/grisu.rs
+++ b/src/libcoretest/num/flt2dec/strategy/grisu.rs
@@ -66,7 +66,7 @@ fn shortest_f32_exhaustive_equivalence_test() {
     f32_exhaustive_equivalence_test(format_shortest_opt, fallback, MAX_SIG_DIGITS);
 }
 
-#[test] #[ignore] // is is too expensive
+#[test] #[ignore] // it is too expensive
 fn shortest_f64_hard_random_equivalence_test() {
     // this again probably has to use appropriate rustc flags.