Documentation improvements (#528)

- Expand documentation on `Limb` representations
- Bernstein-Yang doc cleanups

Author: tarcieri

src/limb.rs

@@ -53,8 +53,11 @@ pub type Word = u64;
 #[cfg(target_pointer_width = "64")]
 pub type WideWord = u128;
 
-/// Big integers are represented as an array of smaller CPU word-size integers
-/// called "limbs".
+/// Big integers are represented as an array/vector of smaller CPU word-size integers called
+/// "limbs".
+///
+/// The [`Limb`] type uses a 32-bit or 64-bit saturated representation, depending on the target.
+/// All bits of an inner [`Word`] are used to represent larger big integer types.
 // Our PartialEq impl only differs from the default one by being constant-time, so this is safe
 #[allow(clippy::derived_hash_with_manual_eq)]
 #[derive(Copy, Clone, Default, Hash)]

src/modular/bernstein_yang.rs

@@ -142,6 +142,7 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> Inverter
 
 /// Returns the multiplicative inverse of the argument modulo 2^62. The implementation is based
 /// on the Hurchalla's method for computing the multiplicative inverse modulo a power of two.
+///
 /// For better understanding the implementation, the following paper is recommended:
 /// J. Hurchalla, "An Improved Integer Multiplicative Inverse (modulo 2^w)",
 /// https://arxiv.org/pdf/2204.04342.pdf
@@ -238,8 +239,9 @@ const fn jump(f: &[u64], g: &[u64], mut delta: i64) -> (i64, Matrix) {
 }
 
 /// 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.
+/// 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>,
@@ -252,10 +254,12 @@ 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).
+/// 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,
@@ -313,7 +317,7 @@ impl<const LIMBS: usize> Int62L<LIMBS> {
         ret
     };
 
-    /// Convert from 64-bit saturated representation used by `Uint` to the 62-bit unsaturated
+    /// Convert from 32/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
@@ -332,13 +336,13 @@ impl<const LIMBS: usize> Int62L<LIMBS> {
         Self(output)
     }
 
-    /// Convert from 62-bit unsaturated representation used by `Int62L` to the 64-bit saturated
+    /// Convert from 62-bit unsaturated representation used by `Int62L` to the 32/64-bit saturated
     /// representation used by `Uint`.
     ///
-    /// Returns a big unsigned integer as an array of 64-bit chunks, which is equal modulo
+    /// Returns a big unsigned integer as an array of 32/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
+    /// The ordering of the chunks in these arrays is little-endian.
     #[allow(trivial_numeric_casts, clippy::wrong_self_convention)]
     pub const fn to_uint<const SAT_LIMBS: usize>(&self) -> Uint<SAT_LIMBS> {
         debug_assert!(!self.is_negative(), "can't convert negative number to Uint");

src/modular/bernstein_yang/boxed.rs

@@ -119,8 +119,9 @@ fn divsteps(
 }
 
 /// 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.
+/// Bernstein-Yang transition matrix multiplied by 2^62.
+///
+/// The returned vector is "matrix * (f, g)' / 2^62", where "'" is the transpose operator.
 fn fg(f: &mut BoxedInt62L, g: &mut BoxedInt62L, t: Matrix) {
     // TODO(tarcieri): reduce allocations
     let mut f2 = &*f * t[0][0];
@@ -136,10 +137,12 @@ fn fg(f: &mut BoxedInt62L, g: &mut BoxedInt62L, t: Matrix) {
 }
 
 /// 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).
+/// 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).
 fn de(modulus: &BoxedInt62L, inverse: i64, t: Matrix, d: &mut BoxedInt62L, e: &mut BoxedInt62L) {
     let mask = BoxedInt62L::MASK as i64;
     let mut md = t[0][0] * d.is_negative() as i64 + t[0][1] * e.is_negative() as i64;
@@ -179,7 +182,7 @@ fn de(modulus: &BoxedInt62L, inverse: i64, t: Matrix, d: &mut BoxedInt62L, e: &m
 #[derive(Clone, Debug)]
 pub(crate) struct BoxedInt62L(Box<[u64]>);
 
-/// Convert from 64-bit saturated representation used by `Uint` to the 62-bit unsaturated
+/// Convert from 32/64-bit saturated representation used by `Uint` to the 62-bit unsaturated
 /// representation used by `BoxedInt62L`.
 ///
 /// Returns a big unsigned integer as an array of 62-bit chunks, which is equal modulo