KaTeXify more of edwards.rs

src/edwards.rs

@@ -52,12 +52,11 @@ use traits::select_precomputed_point;
 // Compressed points
 // ------------------------------------------------------------------------
 
-/// In "Edwards y" format, the point `(x,y)` on the curve is
+/// In "Edwards y" / "Ed25519" format, the curve point \\((x,y)\\) is
-/// determined by the `y`-coordinate and the sign of `x`, marshalled
+/// determined by the \\(y\\)-coordinate and the sign of \\(x\\).
-/// into a 32-byte array.
 ///
 /// The first 255 bits of a `CompressedEdwardsY` represent the
-/// y-coordinate. The high bit of the 32nd byte gives the sign of `x`.
+/// \\(y\\)-coordinate.  The high bit of the 32nd byte gives the sign of \\(x\\).
 #[derive(Copy, Clone, Eq, PartialEq)]
 pub struct CompressedEdwardsY(pub [u8; 32]);
 
@@ -80,9 +79,9 @@ impl CompressedEdwardsY {
 
     /// Attempt to decompress to an `ExtendedPoint`.
     ///
-    /// Returns `None` if the input is not the `y`-coordinate of a
+    /// Returns `None` if the input is not the \\(y\\)-coordinate of a
     /// curve point.
-    pub fn decompress(&self) -> Option<ExtendedPoint> { // FromBytes()
+    pub fn decompress(&self) -> Option<ExtendedPoint> {
         let Y = FieldElement::from_bytes(self.as_bytes());
         let Z = FieldElement::one();
         let YY = Y.square();
@@ -160,8 +159,11 @@ impl<'de> Deserialize<'de> for ExtendedPoint {
 // Internal point representations
 // ------------------------------------------------------------------------
 
-/// An `ExtendedPoint` is a point on the curve in 𝗣³(𝔽ₚ).
+/// An `ExtendedPoint` represents a point on the Edwards form of Curve25519.
-/// A point (x,y) in the affine model corresponds to (x:y:1:xy).
+///
+/// The name refers to the extended twisted Edwards coordinates of
+/// Hisil, Wong, Carter, and Dawson, and more details on curve models
+/// can be found in the `curve25519-dalek` internal documentation.
 #[derive(Copy, Clone)]
 #[allow(missing_docs)]
 pub struct ExtendedPoint {
@@ -233,7 +235,7 @@ impl Equal for ExtendedPoint {
 // ------------------------------------------------------------------------
 
 impl ExtendedPoint {
-    /// Convert to a ProjectiveNielsPoint
+    /// Convert to a `ProjectiveNielsPoint`
     pub(crate) fn to_projective_niels(&self) -> ProjectiveNielsPoint {
         ProjectiveNielsPoint{
             Y_plus_X:  &self.Y + &self.X,
@@ -243,11 +245,10 @@ impl ExtendedPoint {
         }
     }
 
-    /// Convert the representation of this point from extended Twisted Edwards
+    /// Convert the representation of this point from extended
-    /// coodinates to projective coordinates.
+    /// coordinates to projective coordinates.
     ///
-    /// Given a point in Ɛₑ, we can convert to projective coordinates
+    /// Free. 
-    /// cost-free by simply ignoring T.
     pub(crate) fn to_projective(&self) -> ProjectivePoint {
         ProjectivePoint{
             X: self.X,
@@ -428,8 +429,8 @@ impl<'a, 'b> Mul<&'b Scalar> for &'a ExtendedPoint {
     type Output = ExtendedPoint;
     /// Scalar multiplication: compute `scalar * self`.
     ///
-    /// Uses a window of size 4.  Note: for scalar multiplication of
+    /// For scalar multiplication of a basepoint,
-    /// the basepoint, `basepoint_mult` is approximately 4x faster.
+    /// `EdwardsBasepointTable` is approximately 4x faster.
     fn mul(self, scalar: &'b Scalar) -> ExtendedPoint {
         // Construct a lookup table of [P,2P,3P,4P,5P,6P,7P,8P]
         let P = self.to_projective_niels();
@@ -469,27 +470,32 @@ impl<'a, 'b> Mul<&'b Scalar> for &'a ExtendedPoint {
 impl<'a, 'b> Mul<&'b ExtendedPoint> for &'a Scalar {
     type Output = ExtendedPoint;
 
-    /// Scalar multiplication: compute `self * point`.
+    /// Scalar multiplication: compute `scalar * self`.
     ///
-    /// Uses a window of size 4.  Note: for scalar multiplication of
+    /// For scalar multiplication of a basepoint,
-    /// the basepoint, `basepoint_mult` is approximately 4x faster.
+    /// `EdwardsBasepointTable` is approximately 4x faster.
     fn mul(self, point: &'b ExtendedPoint) -> ExtendedPoint {
         point * &self
     }
 }
 
-/// Given a vector of (possibly secret) scalars and a vector of
+/// Given an iterator of (possibly secret) scalars and an iterator of
-/// (possibly secret) points, compute `c_1 P_1 + ... + c_n P_n`.
+/// (possibly secret) points, compute
+/// $$
+/// Q = c\_1 P\_1 + \cdots + c\_n P\_n.
+/// $$
 ///
 /// This function has the same behaviour as
 /// `vartime::multiscalar_mult` but is constant-time.
 ///
 /// # Input
 ///
-/// A vector of `Scalar`s and a vector of `ExtendedPoints`.  It is an
+/// A iterable of `Scalar`s and a iterable of `ExtendedPoints`.  It is an
-/// error to call this function with two vectors of different lengths.
+/// error to call this function with two iterators of different lengths.
 /// 
 /// XXX need to clear memory
+// XXX later when we do more fancy multiscalar mults, we can delegate
+// based on the iter's size hint -- hdevalence
 #[cfg(any(feature = "alloc", feature = "std"))]
 pub fn multiscalar_mult<'a, 'b, I, J>(scalars: I, points: J) -> ExtendedPoint
     where I: IntoIterator<Item = &'a Scalar>,
@@ -674,13 +680,20 @@ impl ExtendedPoint {
 
     /// Determine if this point is of small order.
     ///
-    /// The order of the group of points on the curve Ɛ is |Ɛ| = 8q.  Thus, to
+    /// The order of the group of points on the curve \\(\mathcal E\\)
-    /// check if a point P is of small order, we multiply by 8 and then test
+    /// is \\(|\mathcal E| = 8\ell \\), so its structure is \\( \mathcal
-    /// if the result is equal to the identity.
+    /// E = \mathcal E[8] \times \mathcal E[\ell]\\).  The torsion
+    /// subgroup \\( \mathcal E[8] \\) consists of eight points of small
+    /// order.  (Technically all of \\(\mathcal E\\) is torsion, but we
+    /// use the word only to refer to the \\(\mathcal E[8]\\) part, not
+    /// the prime-order subgroup \\(\mathcal E[\ell]\\).
+    ///
+    /// For more information on cofactors and the group structure, see
+    /// the internal `curve25519-dalek` documentation on Ristretto.
     ///
     /// # Return
     ///
-    /// True if it is of small order; false otherwise.
+    /// True if `self` is of small order; false otherwise.
     pub fn is_small_order(&self) -> bool {
         self.mult_by_cofactor().is_identity()
     }
@@ -764,13 +777,16 @@ pub mod vartime {
         }
     }
 
-    /// Given a vector of public scalars and a vector of (possibly secret)
+    /// Given an iterable of public scalars and an iterable of public
-    /// points, compute `c_1 P_1 + ... + c_n P_n`.
+    /// points, compute
+    /// $$
+    /// Q = c\_1 P\_1 + \cdots + c\_n P\_n.
+    /// $$
     ///
     /// # Input
     ///
-    /// A vector of `Scalar`s and a vector of `ExtendedPoints`.  It is an
+    /// A iterable of `Scalar`s and a iterable of `ExtendedPoints`.  It is an
-    /// error to call this function with two vectors of different lengths.
+    /// error to call this function with two iterators of different lengths.
     #[cfg(any(feature = "alloc", feature = "std"))]
     pub fn multiscalar_mult<'a, 'b, I, J>(scalars: I, points: J) -> ExtendedPoint
         where I: IntoIterator<Item = &'a Scalar>,
@@ -802,8 +818,8 @@ pub mod vartime {
         r.to_extended()
     }
 
-    /// Given a point `A` and scalars `a` and `b`, compute the point
+    /// Given a point \\(A\\) and scalars \\(a\\) and \\(b\\), compute the point
-    /// `aA+bB`, where `B` is the Ed25519 basepoint (i.e., `B = (x,4/5)`
+    /// \\(aA+bB\\), where \\(B\\) is the Ed25519 basepoint (i.e., \\(B = (x,4/5)\\)
     /// with x positive).
     #[cfg(feature="precomputed_tables")]
     pub fn double_scalar_mult_basepoint(a: &Scalar,