Bernstein-Yang: comment reformatting

Author: tarcieri

src/modular/bernstein_yang.rs

@@ -18,22 +18,22 @@ use subtle::CtOption;
 
 /// Modular multiplicative inverter based on the Bernstein-Yang method.
 ///
-/// The inverter can be created for a specified modulus M and adjusting parameter A
-/// to compute the adjusted multiplicative inverses of positive integers, i.e. for
-/// computing (1 / x) * A (mod M) for a positive integer x.
+/// The inverter can be created for a specified modulus M and adjusting parameter A to compute
+/// the adjusted multiplicative inverses of positive integers, i.e. for computing
+/// (1 / x) * A (mod M) for a positive integer x.
 ///
-/// The adjusting parameter allows computing the multiplicative inverses in the case of
-/// using the Montgomery representation for the input or the expected output. If R is
-/// the Montgomery factor, the multiplicative inverses in the appropriate representation
-/// can be computed provided that the value of A is chosen as follows:
+/// The adjusting parameter allows computing the multiplicative inverses in the case of using the
+/// Montgomery representation for the input or the expected output. If R is the Montgomery
+/// factor, the multiplicative inverses in the appropriate representation can be computed
+/// provided that the value of A is chosen as follows:
 /// - A = 1, if both the input and the expected output are in the standard form
 /// - A = R^2 mod M, if both the input and the expected output are in the Montgomery form
 /// - A = R mod M, if either the input or the expected output is in the Montgomery form,
 /// but not both of them
 ///
-/// The public methods of this type receive and return unsigned big integers as arrays of
-/// 64-bit chunks, the ordering of which is little-endian. Both the modulus and the integer
-/// to be inverted should not exceed 2 ^ (62 * L - 64)
+/// The public methods of this type receive and return unsigned big integers as arrays of 64-bit
+/// chunks, the ordering of which is little-endian. Both the modulus and the integer to be
+/// inverted should not exceed 2 ^ (62 * L - 64).
 ///
 /// For better understanding the implementation, the following resources are recommended:
 /// - D. Bernstein, B.-Y. Yang, "Fast constant-time gcd computation and modular inversion",
@@ -45,7 +45,7 @@ pub struct BernsteinYangInverter<const SAT_LIMBS: usize, const UNSAT_LIMBS: usiz
     /// Modulus
     pub(super) modulus: Int62L<UNSAT_LIMBS>,
 
-    /// Adjusting parameter
+    /// Adjusting parameter (see toplevel documentation).
     adjuster: Int62L<UNSAT_LIMBS>,
 
     /// Multiplicative inverse of the modulus modulo 2^62
@@ -86,9 +86,9 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
             (f, g) = fg(f, g, matrix);
             (d, e) = de(&self.modulus, self.inverse, d, e, matrix);
         }
-        // At this point the absolute value of "f" equals the greatest common divisor
-        // of the integer to be inverted and the modulus the inverter was created for.
-        // Thus, if "f" is neither 1 nor -1, then the sought inverse does not exist
+        // At this point the absolute value of "f" equals the greatest common divisor of the
+        // integer to be inverted and the modulus the inverter was created for.
+        // Thus, if "f" is neither 1 nor -1, then the sought inverse does not exist.
         let antiunit = f.eq(&Int62L::MINUS_ONE);
         let ret = self.norm(d, antiunit);
         let is_some = ConstChoice::from_word_lsb((f.eq(&Int62L::ONE) || antiunit) as Word);
@@ -97,8 +97,9 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
 
     /// Returns the greatest common divisor (GCD) of the two given numbers.
     ///
-    /// This is defined on this type to piggyback on the definitions for `SAT_LIMBS` and `UNSAT_LIMBS` which are
-    /// computed when defining `PrecomputeInverter::Inverter` for various `Uint` limb sizes.
+    /// This is defined on this type to piggyback on the definitions for `SAT_LIMBS` and
+    /// `UNSAT_LIMBS` which are computed when defining `PrecomputeInverter::Inverter` for various
+    /// `Uint` limb sizes.
     pub(crate) const fn gcd(f: &Uint<SAT_LIMBS>, g: &Uint<SAT_LIMBS>) -> Uint<SAT_LIMBS> {
         let f_0 = Int62L::from_uint(f);
         let inverse = inv_mod2_62(f.as_words());
@@ -123,9 +124,9 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
         f.to_uint()
     }
 
-    /// Returns the Bernstein-Yang transition matrix multiplied by 2^62 and the new value
-    /// of the delta variable for the 62 basic steps of the Bernstein-Yang method, which
-    /// are to be performed sequentially for specified initial values of f, g and delta
+    /// Returns the Bernstein-Yang transition matrix multiplied by 2^62 and the new value of the
+    /// delta variable for the 62 basic steps of the Bernstein-Yang method, which are to be
+    /// performed sequentially for specified initial values of f, g and delta
     const fn jump(
         f: &Int62L<UNSAT_LIMBS>,
         g: &Int62L<UNSAT_LIMBS>,
@@ -156,9 +157,9 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
                 (t[0], t[1]) = (t[1], [-t[0][0], -t[0][1]]);
             }
 
-            // The formula (3 * x) xor 28 = -1 / x (mod 32) for an odd integer x
-            // in the two's complement code has been derived from the formula
-            // (3 * x) xor 2 = 1 / x (mod 32) attributed to Peter Montgomery
+            // The formula (3 * x) xor 28 = -1 / x (mod 32) for an odd integer x in the two's
+            // complement code has been derived from the formula (3 * x) xor 2 = 1 / x (mod 32)
+            // attributed to Peter Montgomery.
             let mask = (1 << min(min(steps, 1 - delta), 5)) - 1;
             let w = (g as i64).wrapping_mul(f.wrapping_mul(3) ^ 28) & mask;
 
@@ -169,9 +170,9 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
         (delta, t)
     }
 
-    /// Returns either "value (mod M)" or "-value (mod M)", where M is the modulus the
-    /// inverter was created for, depending on "negate", which determines the presence
-    /// of "-" in the used formula. The input integer lies in the interval (-2 * M, M)
+    /// Returns either "value (mod M)" or "-value (mod M)", where M is the modulus the inverter
+    /// was created for, depending on "negate", which determines the presence of "-" in the used
+    /// formula. The input integer lies in the interval (-2 * M, M).
     const fn norm(&self, mut value: Int62L<UNSAT_LIMBS>, negate: bool) -> Int62L<UNSAT_LIMBS> {
         if value.is_negative() {
             value = value.add(&self.modulus);
@@ -226,8 +227,9 @@ const fn inv_mod2_62(value: &[Word]) -> i64 {
     (x.wrapping_mul(y.wrapping_add(1)) & (u64::MAX >> 2)) as i64
 }
 
-/// Returns the updated values of the variables f and g for specified initial ones and Bernstein-Yang transition
-/// matrix multiplied by 2^62. The returned vector is "matrix * (f, g)' / 2^62", where "'" is the transpose operator
+/// Returns the updated values of the variables f and g for specified initial ones and
+/// Bernstein-Yang transition matrix multiplied by 2^62. The returned vector is
+/// "matrix * (f, g)' / 2^62", where "'" is the transpose operator.
 const fn fg<const LIMBS: usize>(
     f: Int62L<LIMBS>,
     g: Int62L<LIMBS>,
@@ -239,10 +241,11 @@ const fn fg<const LIMBS: usize>(
     )
 }
 
-/// Returns the updated values of the variables d and e for specified initial ones and Bernstein-Yang transition
-/// matrix multiplied by 2^62. The returned vector is congruent modulo M to "matrix * (d, e)' / 2^62 (mod M)",
-/// where M is the modulus the inverter was created for and "'" stands for the transpose operator. Both the input
-/// and output values lie in the interval (-2 * M, M)
+/// Returns the updated values of the variables d and e for specified initial ones and
+/// Bernstein-Yang transition matrix multiplied by 2^62. The returned vector is congruent modulo
+/// M to "matrix * (d, e)' / 2^62 (mod M)", where M is the modulus the inverter was created for
+/// and "'" stands for the transpose operator. Both the input and output values lie in the
+/// interval (-2 * M, M).
 const fn de<const LIMBS: usize>(
     modulus: &Int62L<LIMBS>,
     inverse: i64,
@@ -273,8 +276,8 @@ const fn de<const LIMBS: usize>(
     (cd.shr(), ce.shr())
 }
 
-/// "Bigint"-like (62 * LIMBS)-bit signed integer type, whose variables store numbers in the two's complement code as
-/// arrays of 62-bit limbs in little endian order.
+/// "Bigint"-like (62 * LIMBS)-bit signed integer type, whose variables store numbers in the two's
+/// complement code as arrays of 62-bit limbs in little endian order.
 ///
 /// The arithmetic operations for this type are wrapping ones.
 #[derive(Clone, Copy, Debug)]
@@ -300,11 +303,11 @@ impl<const LIMBS: usize> Int62L<LIMBS> {
         ret
     };
 
-    /// Convert from 64-bit saturated representation used by `Uint` to the 62-bit unsaturated representation used by
-    /// `Uint62L`.
+    /// Convert from 64-bit saturated representation used by `Uint` to the 62-bit unsaturated
+    /// representation used by `Int62L`.
     ///
-    /// Returns a big unsigned integer as an array of 62-bit chunks, which is equal modulo 2 ^ (62 * S) to the input big
-    /// unsigned integer stored as an array of 64-bit chunks.
+    /// Returns a big unsigned integer as an array of 62-bit chunks, which is equal modulo
+    /// 2 ^ (62 * S) to the input big unsigned integer stored as an array of 64-bit chunks.
     ///
     /// The ordering of the chunks in these arrays is little-endian.
     #[allow(trivial_numeric_casts)]
@@ -319,11 +322,11 @@ impl<const LIMBS: usize> Int62L<LIMBS> {
         Self(output)
     }
 
-    /// Convert from 62-bit unsaturated representation used by `Uint62L` to the 64-bit saturated representation used by
-    /// `Uint`.
+    /// Convert from 62-bit unsaturated representation used by `Int62L` to the 64-bit saturated
+    /// representation used by `Uint`.
     ///
-    /// Returns a big unsigned integer as an array of 64-bit chunks, which is equal modulo 2 ^ (64 * S) to the input big
-    /// unsigned integer stored as an array of 62-bit chunks.
+    /// Returns a big unsigned integer as an array of 64-bit chunks, which is equal modulo
+    /// 2 ^ (64 * S) to the input big unsigned integer stored as an array of 62-bit chunks.
     ///
     /// The ordering of the chunks in these arrays is little-endian
     #[allow(trivial_numeric_casts, clippy::wrong_self_convention)]
@@ -359,18 +362,18 @@ impl<const LIMBS: usize> Int62L<LIMBS> {
     /// Const fn equivalent for `Mul::<i64>::mul`.
     pub const fn mul(&self, other: i64) -> Self {
         let mut ret = Self::ZERO;
-        // If the short multiplicand is non-negative, the standard multiplication
-        // algorithm is performed. Otherwise, the product of the additively negated
-        // multiplicands is found as follows. Since for the two's complement code
-        // the additive negation is the result of adding 1 to the bitwise inverted
-        // argument's representation, for any encoded integers x and y we have
-        // x * y = (-x) * (-y) = (!x + 1) * (-y) = !x * (-y) + (-y),  where "!" is
-        // the bitwise inversion and arithmetic operations are performed according
-        // to the rules of the code. If the short multiplicand is negative, the
-        // algorithm below uses this formula by substituting the short multiplicand
-        // for y and turns into the modified standard multiplication algorithm,
-        // where the carry flag is initialized with the additively negated short
-        // multiplicand and the chunks of the long multiplicand are bitwise inverted
+        // If the short multiplicand is non-negative, the standard multiplication algorithm is
+        // performed. Otherwise, the product of the additively negated multiplicands is found as
+        // follows.
+        //
+        // Since for the two's complement code the additive negation is the result of adding 1 to
+        // the bitwise inverted argument's representation, for any encoded integers x and y we have
+        // x * y = (-x) * (-y) = (!x + 1) * (-y) = !x * (-y) + (-y),  where "!" is the bitwise
+        // inversion and arithmetic operations are performed according to the rules of the code.
+        // If the short multiplicand is negative, the algorithm below uses this formula by
+        // substituting the short multiplicand for y and turns into the modified standard
+        // multiplication algorithm, where the carry flag is initialized with the additively
+        // negated short multiplicand and the chunks of the long multiplicand are bitwise inverted.
         let (other, mut carry, mask) = if other < 0 {
             (-other, -other as u64, Self::MASK)
         } else {
@@ -390,8 +393,8 @@ impl<const LIMBS: usize> Int62L<LIMBS> {
 
     /// Const fn equivalent for `Neg::neg`.
     pub const fn neg(&self) -> Self {
-        // For the two's complement code the additive negation is the result
-        // of adding 1 to the bitwise inverted argument's representation
+        // For the two's complement code the additive negation is the result of adding 1 to the
+        // bitwise inverted argument's representation.
         let (mut ret, mut carry) = (Self::ZERO, 1);
         let mut i = 0;