Add explanation for normalization shift code

Author: ChaiTRex

library/core/src/num/int_sqrt.rs

@@ -115,6 +115,36 @@ macro_rules! unsigned_fn {
             if n <= <$HalfBitsT>::MAX as $UnsignedT {
                 $HalfBitsT(n as $HalfBitsT) as $UnsignedT
             } else {
+                // The normalization shift satisfies the Karatsuba square root
+                // algorithm precondition "a₃ ≥ b/4" where a₃ is the most
+                // significant quarter of the bits and b is the number of
+                // values in `$UnsignedT`.
+                //
+                // In binary, b would thus be 1 followed by a count of
+                // `<$UnsignedT>::BITS` 0s. b/4 would then be 1 followed by
+                // `<$UnsignedT>::BITS - 2` 0s. a₃ must then be at least b/4,
+                // which means that the most significant bit or its neighbor
+                // must be a 1.
+                //
+                // The reason to shift by an even number of bits is because an
+                // even number of bits produces the square root shifted to the
+                // left by half of the normalization shift:
+                //
+                // sqrt(n << (2 * p))
+                // sqrt(2.pow(2 * p) * n)
+                // sqrt(2.pow(2 * p)) * sqrt(n)
+                // 2.pow(p) * sqrt(n)
+                // sqrt(n) << p
+                //
+                // Shifting by an odd number of bits leaves an ugly sqrt(2)
+                // multiplied in:
+                //
+                // sqrt(n << (2 * p + 1))
+                // sqrt(2.pow(2 * p + 1) * n)
+                // sqrt(2 * 2.pow(2 * p) * n)
+                // sqrt(2) * sqrt(2.pow(2 * p)) * sqrt(n)
+                // sqrt(2) * 2.pow(p) * sqrt(n)
+                // sqrt(2) * (sqrt(n) << p)
                 const EVEN_MAKING_BITMASK: u32 = !1;
                 let normalization_shift = n.leading_zeros() & EVEN_MAKING_BITMASK;
                 n <<= normalization_shift;