core: fixed more comments and slight bug.

The bug involves the incorrect logic for `core::num::flt2dec::decoder`.
Fortunately, we have been already testing this case (the minimal
normalized value) so there is no regression for this slight bug.

src/libcore/num/flt2dec/bignum.rs

@@ -216,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;

src/libcore/num/flt2dec/decoder.rs

@@ -73,7 +73,7 @@ pub fn decode<T: DecodableFloat>(v: T) -> (/*negative?*/ bool, FullDecoded) {
         FpCategory::Infinite => FullDecoded::Infinite,
         FpCategory::Zero => FullDecoded::Zero,
         FpCategory::Subnormal => {
-            // (mant - 2, exp) -- (mant, exp) -- (mant + 2, exp)
+            // neighbors: (mant - 2, exp) -- (mant, exp) -- (mant + 2, exp)
             // Float::integer_decode always preserves the exponent,
             // so the mantissa is scaled for subnormals.
             FullDecoded::Finite(Decoded { mant: mant, minus: 1, plus: 1,
@@ -82,12 +82,12 @@ pub fn decode<T: DecodableFloat>(v: T) -> (/*negative?*/ bool, FullDecoded) {
         FpCategory::Normal => {
             let minnorm = <T as DecodableFloat>::min_pos_norm_value().integer_decode();
             if mant == minnorm.0 && exp == minnorm.1 {
-                // (maxmant, exp - 1) -- (minnormmant, exp) -- (minnormmant + 1, exp)
+                // neighbors: (maxmant, exp - 1) -- (minnormmant, exp) -- (minnormmant + 1, exp)
                 // where maxmant = minnormmant * 2 - 1
-                FullDecoded::Finite(Decoded { mant: mant << 1, minus: 1, plus: 2,
-                                              exp: exp - 1, inclusive: even })
+                FullDecoded::Finite(Decoded { mant: mant << 2, minus: 1, plus: 2,
+                                              exp: exp - 2, inclusive: even })
             } else {
-                // (mant - 1, exp) -- (mant, exp) -- (mant + 1, exp)
+                // neighbors: (mant - 1, exp) -- (mant, exp) -- (mant + 1, exp)
                 FullDecoded::Finite(Decoded { mant: mant << 1, minus: 1, plus: 1,
                                               exp: exp - 1, inclusive: even })
             }

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
 }