core: fixed typos and misleading comments in flt2dec.

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]
         }
 
@@ -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 {

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
@@ -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]