From a743ea53487cdd300657db37e45892c4e503add4 Mon Sep 17 00:00:00 2001 From: Michael Rosenberg Date: Sat, 22 Oct 2022 14:39:40 -0400 Subject: [PATCH] Fixed doc warnings --- docs/parallel-formulas.md | 2 +- src/backend/serial/mod.rs | 3 +-- src/backend/serial/u32/constants.rs | 8 +++---- src/backend/serial/u64/constants.rs | 10 ++++----- src/edwards.rs | 33 +++++++++++++++-------------- src/montgomery.rs | 4 ++-- src/ristretto.rs | 6 +++--- src/traits.rs | 14 ++++++------ 8 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/parallel-formulas.md b/docs/parallel-formulas.md index f84d1cc..9472736 100644 --- a/docs/parallel-formulas.md +++ b/docs/parallel-formulas.md @@ -207,7 +207,7 @@ $$ (S\_8 \cdot S\_9 &&,&& S\_5 \cdot S\_6 &&,&& S\_8 \cdot S\_6 &&,&& S\_5 \cdot S\_9) \end{aligned} $$ -to obtain \\( P\_3 = (X\_3 : Y\_3 : Z\_3 : T\_3) = [2]P\_1 \\). +to obtain \\( P\_3 = (X\_3 : Y\_3 : Z\_3 : T\_3) = \[2\]P\_1 \\). The intermediate step between the squaring and multiplication requires a long chain of additions. For the IFMA-based implementation, this is not a problem; for the AVX2-based implementation, it is, but with some care and finesse, it's possible to arrange the computation without requiring an intermediate reduction. diff --git a/src/backend/serial/mod.rs b/src/backend/serial/mod.rs index 3649604..4e3a179 100644 --- a/src/backend/serial/mod.rs +++ b/src/backend/serial/mod.rs @@ -14,8 +14,7 @@ //! When the vector backend is disabled, the crate uses the //! mixed-model strategy for implementing point operations and scalar //! multiplication; see the [`curve_models`](self::curve_models) and -//! [`scalar_mul`](self::scalar_mul) documentation for more -//! information. +//! [`scalar_mul`] documentation for more information. //! //! When the vector backend is enabled, the field and scalar //! implementations are still used for non-vectorized operations. diff --git a/src/backend/serial/u32/constants.rs b/src/backend/serial/u32/constants.rs index c795658..eec7c9e 100644 --- a/src/backend/serial/u32/constants.rs +++ b/src/backend/serial/u32/constants.rs @@ -122,14 +122,14 @@ pub const ED25519_BASEPOINT_POINT: EdwardsPoint = EdwardsPoint { ]), }; -/// The 8-torsion subgroup \\(\mathcal E [8]\\). +/// The 8-torsion subgroup \\(\mathcal E \[8\]\\). /// /// In the case of Curve25519, it is cyclic; the \\(i\\)-th element of /// the array is \\([i]P\\), where \\(P\\) is a point of order \\(8\\) -/// generating \\(\mathcal E[8]\\). +/// generating \\(\mathcal E\[8\]\\). /// -/// Thus \\(\mathcal E[4]\\) is the points indexed by `0,2,4,6`, and -/// \\(\mathcal E[2]\\) is the points indexed by `0,4`. +/// Thus \\(\mathcal E\[4\]\\) is the points indexed by `0,2,4,6`, and +/// \\(\mathcal E\[2\]\\) is the points indexed by `0,4`. /// The Ed25519 basepoint has y = 4/5. This is called `_POINT` to /// distinguish it from `_TABLE`, which should be used for scalar /// multiplication (it's much faster). diff --git a/src/backend/serial/u64/constants.rs b/src/backend/serial/u64/constants.rs index bc41719..64368b8 100644 --- a/src/backend/serial/u64/constants.rs +++ b/src/backend/serial/u64/constants.rs @@ -167,14 +167,14 @@ pub const ED25519_BASEPOINT_POINT: EdwardsPoint = EdwardsPoint { ]), }; -/// The 8-torsion subgroup \\(\mathcal E [8]\\). +/// The 8-torsion subgroup \\(\mathcal E \[8\]\\). /// /// In the case of Curve25519, it is cyclic; the \\(i\\)-th element of -/// the array is \\([i]P\\), where \\(P\\) is a point of order \\(8\\) -/// generating \\(\mathcal E[8]\\). +/// the array is \\(\[i\]P\\), where \\(P\\) is a point of order \\(8\\) +/// generating \\(\mathcal E\[8\]\\). /// -/// Thus \\(\mathcal E[4]\\) is the points indexed by `0,2,4,6`, and -/// \\(\mathcal E[2]\\) is the points indexed by `0,4`. +/// Thus \\(\mathcal E\[4\]\\) is the points indexed by `0,2,4,6`, and +/// \\(\mathcal E\[2\]\\) is the points indexed by `0,4`. pub const EIGHT_TORSION: [EdwardsPoint; 8] = EIGHT_TORSION_INNER_DOC_HIDDEN; /// Inner item used to hide limb constants from cargo doc output. diff --git a/src/edwards.rs b/src/edwards.rs index 24c2b05..77add9c 100644 --- a/src/edwards.rs +++ b/src/edwards.rs @@ -18,7 +18,7 @@ //! //! ## Equality Testing //! -//! The `EdwardsPoint` struct implements the `subtle::ConstantTimeEq` +//! The `EdwardsPoint` struct implements the [`subtle::ConstantTimeEq`] //! trait for constant-time equality checking, and the Rust `Eq` trait //! for variable-time equality checking. //! @@ -26,26 +26,26 @@ //! //! The order of the group of points on the curve \\(\mathcal E\\) //! is \\(|\mathcal E| = 8\ell \\), so its structure is \\( \mathcal -//! E = \mathcal E[8] \times \mathcal E[\ell]\\). The torsion -//! subgroup \\( \mathcal E[8] \\) consists of eight points of small +//! 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 small \\(\mathcal E[8]\\) part, not +//! use the word only to refer to the small \\(\mathcal E\[8\]\\) part, not //! the large prime-order \\(\mathcal E[\ell]\\) part. //! -//! To test if a point is in \\( \mathcal E[8] \\), use -//! `EdwardsPoint::is_small_order()`. +//! To test if a point is in \\( \mathcal E\[8\] \\), use +//! [`EdwardsPoint::is_small_order`]. //! //! To test if a point is in \\( \mathcal E[\ell] \\), use -//! `EdwardsPoint::is_torsion_free()`. +//! [`EdwardsPoint::is_torsion_free`]. //! -//! To multiply by the cofactor, use `EdwardsPoint::mul_by_cofactor()`. +//! To multiply by the cofactor, use [`EdwardsPoint::mul_by_cofactor`]. //! //! To avoid dealing with cofactors entirely, consider using Ristretto. //! //! ## Scalars //! -//! Scalars are represented by the `Scalar` struct. To construct a scalar with a specific bit -//! pattern, see `Scalar::from_bits()`. +//! Scalars are represented by the [`Scalar`] struct. To construct a scalar with a specific bit +//! pattern, see [`Scalar::from_bits`]. //! //! ## Scalar Multiplication //! @@ -825,7 +825,7 @@ macro_rules! impl_basepoint_table { (Name = $name:ident, LookupTable = $table:ident, Point = $point:ty, Radix = $radix:expr, Additions = $adds:expr) => { /// A precomputed table of multiples of a basepoint, for accelerating /// fixed-base scalar multiplication. One table, for the Ed25519 - /// basepoint, is provided in the `constants` module. + /// basepoint, is provided in the [`constants`] module. /// /// The basepoint tables are reasonably large, so they should probably be boxed. /// @@ -833,7 +833,8 @@ macro_rules! impl_basepoint_table { /// multiplication are as follows: /// /// * [`EdwardsBasepointTableRadix16`]: 30KB, 64A - /// (this is the default size, and is used for [`ED25519_BASEPOINT_TABLE`]) + /// (this is the default size, and is used for + /// [`constants::ED25519_BASEPOINT_TABLE`]) /// * [`EdwardsBasepointTableRadix64`]: 120KB, 43A /// * [`EdwardsBasepointTableRadix128`]: 240KB, 37A /// * [`EdwardsBasepointTableRadix256`]: 480KB, 33A @@ -978,7 +979,7 @@ impl_basepoint_table! {Name = EdwardsBasepointTableRadix128, LookupTable = Looku impl_basepoint_table! {Name = EdwardsBasepointTableRadix256, LookupTable = LookupTableRadix256, Point = EdwardsPoint, Radix = 8, Additions = 33} /// A type-alias for [`EdwardsBasepointTable`] because the latter is -/// used as a constructor in the `constants` module. +/// used as a constructor in the [`constants`] module. // // Same as for `LookupTableRadix16`, we have to define `EdwardsBasepointTable` // first, because it's used as a constructor, and then provide a type alias for @@ -1016,7 +1017,7 @@ impl_basepoint_table_conversions! {LHS = EdwardsBasepointTableRadix64, RHS = Edw impl_basepoint_table_conversions! {LHS = EdwardsBasepointTableRadix128, RHS = EdwardsBasepointTableRadix256} impl EdwardsPoint { - /// Multiply by the cofactor: return \\([8]P\\). + /// Multiply by the cofactor: return \\(\[8\]P\\). pub fn mul_by_cofactor(&self) -> EdwardsPoint { self.mul_by_pow_2(3) } @@ -1038,8 +1039,8 @@ impl EdwardsPoint { /// /// # Return /// - /// * `true` if `self` is in the torsion subgroup \\( \mathcal E[8] \\); - /// * `false` if `self` is not in the torsion subgroup \\( \mathcal E[8] \\). + /// * `true` if `self` is in the torsion subgroup \\( \mathcal E\[8\] \\); + /// * `false` if `self` is not in the torsion subgroup \\( \mathcal E\[8\] \\). /// /// # Example /// diff --git a/src/montgomery.rs b/src/montgomery.rs index 53c76fb..a34330b 100644 --- a/src/montgomery.rs +++ b/src/montgomery.rs @@ -253,7 +253,7 @@ impl ProjectivePoint { /// and the affine difference /// \\( u\_{P-Q} = u(P-Q) \\), set /// $$ -/// (U\_P : W\_P) \gets u([2]P) +/// (U\_P : W\_P) \gets u(\[2\]P) /// $$ /// and /// $$ @@ -317,7 +317,7 @@ define_mul_variants!( impl<'a, 'b> Mul<&'b Scalar> for &'a MontgomeryPoint { type Output = MontgomeryPoint; - /// Given `self` \\( = u\_0(P) \\), and a `Scalar` \\(n\\), return \\( u\_0([n]P) \\). + /// Given `self` \\( = u\_0(P) \\), and a `Scalar` \\(n\\), return \\( u\_0(\[n\]P) \\). fn mul(self, scalar: &'b Scalar) -> MontgomeryPoint { // Algorithm 8 of Costello-Smith 2017 let affine_u = FieldElement::from_bytes(&self.0); diff --git a/src/ristretto.rs b/src/ristretto.rs index fe59cac..38a6925 100644 --- a/src/ristretto.rs +++ b/src/ristretto.rs @@ -124,7 +124,7 @@ //! ## Implementation //! //! The Decaf suggestion is to use a quotient group, such as \\(\mathcal -//! E / \mathcal E[4]\\) or \\(2 \mathcal E / \mathcal E[2] \\), to +//! E / \mathcal E\[4\]\\) or \\(2 \mathcal E / \mathcal E\[2\] \\), to //! implement a prime-order group using a non-prime-order curve. //! //! This requires only changing @@ -498,7 +498,7 @@ impl RistrettoPoint { /// /// However, given input points \\( P\_1, \ldots, P\_n, \\) /// it is possible to compute the encodings of their doubles \\( - /// \mathrm{enc}( [2]P\_1), \ldots, \mathrm{enc}( [2]P\_n ) \\) + /// \mathrm{enc}( \[2\]P\_1), \ldots, \mathrm{enc}( \[2\]P\_n ) \\) /// in a batch. /// /// ``` @@ -605,7 +605,7 @@ impl RistrettoPoint { .collect() } - /// Return the coset self + E[4], for debugging. + /// Return the coset self + E\[4\], for debugging. fn coset4(&self) -> [EdwardsPoint; 4] { [ self.0, diff --git a/src/traits.rs b/src/traits.rs index 5633f5a..ce770ea 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -263,15 +263,15 @@ pub trait VartimeMultiscalarMul { /// /// This trait has three methods for performing this computation: /// -/// * [`vartime_multiscalar_mul`], which handles the special case -/// where \\(n = 0\\) and there are no dynamic points; +/// * [`Self::vartime_multiscalar_mul`], which handles the special case where +/// \\(n = 0\\) and there are no dynamic points; /// -/// * [`vartime_mixed_multiscalar_mul`], which takes the dynamic -/// points as already-validated `Point`s and is infallible; +/// * [`Self::vartime_mixed_multiscalar_mul`], which takes the dynamic points as +/// already-validated `Point`s and is infallible; /// -/// * [`optional_mixed_multiscalar_mul`], which takes the dynamic -/// points as `Option`s and returns an `Option`, -/// allowing decompression to be composed into the input iterators. +/// * [`Self::optional_mixed_multiscalar_mul`], which takes the dynamic points +/// as `Option`s and returns an `Option`, allowing decompression +/// to be composed into the input iterators. /// /// All methods require that the lengths of the input iterators be /// known and matching, as if they were `ExactSizeIterator`s. (It