More edits on doctests

.github/workflows/rust.yml

@@ -23,5 +23,7 @@ jobs:
       run: cargo build --verbose
     - name: Run tests
       run: cargo test --verbose
+      env:
+        RUSTFLAGS: "-D warnings"
     - name: Doc builds
       run: cargo ourdoc

ec/src/curve_weierstrass.rs

@@ -8,17 +8,56 @@
 //! y^2 + a_1 xy + a_3 y = x^3 + a_2 x^2 + a_4 x + a_6
 //! $$
 //!
-//! This form is valid in *any* characteristic, including characteristic $2$.
+//! This form is valid in *any* characteristic (provided the
+//! discriminant is nonzero), including characteristic $2$. This is
+//! enabled via the constructor [`WeierstrassCurve::new`].
 //!
 //! # Short Weierstrass specialisation
 //!
-//! When $\mathrm{char}(F) \ne 2, 3$ the curve can be brought to the simpler
+//! When $\mathrm{char}(F) \ne 2, 3$ the curve can be brought to the
+//! simpler
 //!
 //! $$
-//! y^2 = x^3 + ax + b \quad (a_1 = a_2 = a_3 = 0,\; a_4 = a,\; a_6 = b)
+//! y^2 = x^3 + ax + b
 //! $$
 //!
-//! via the convenience constructor [`WeierstrassCurve::new_short`].
+//! so that $a_1 = a_2 = a_3 = 0$, $a_4 = a$ and a_6 = b$. This is
+//! enabled via the constructor [`WeierstrassCurve::new_short`].
+//!
+//! # Examples
+//!
+//! ```
+//! use crypto_bigint::{Uint, const_prime_monty_params};
+//! use ec::curve_weierstrass::WeierstrassCurve;
+//! use fp::field_ops::FieldOps;
+//! use fp::fp_element::FpElement;
+//!
+//! const_prime_monty_params!(Fp19Mod, Uint<1>, "0000000000000013", 2);
+//! type F19 = FpElement<Fp19Mod, 1>;
+//!
+//! fn fp(n: u64) -> F19 {
+//!     F19::from_u64(n)
+//! }
+//!
+//! /* y^2 = x^3 + 2*x + 3 */
+//! let c = WeierstrassCurve::new_short(fp(2), fp(3));
+//! let c_too = WeierstrassCurve::new(fp(0), fp(0), fp(0), fp(2), fp(3));
+//!
+//! /* They're the same curve */
+//! assert_eq!(c, c_too);
+//!
+//! /* The a-invariants are correct */
+//! assert_eq!(c.a4, fp(2));
+//! assert_eq!(c.a6, fp(3));
+//!
+//! /* Curve is smooth */
+//! assert!(!bool::from(c.discriminant().is_zero()));
+//!
+//! /* (1,5) is a point on c */
+//! assert!(c.contains(&fp(1), &fp(5)));
+//!
+//! /* (0,0) is not a point on c */
+//! assert!(!c.contains(&fp(0), &fp(0)));
 
 use core::fmt;
 use fp::field_ops::{FieldOps, FieldRandom};
@@ -38,15 +77,15 @@ use crate::point_weierstrass::AffinePoint;
 /// case simply has $a_1 = a_2 = a_3 = 0$.
 #[derive(Debug, Clone, PartialEq, Eq, Copy)]
 pub struct WeierstrassCurve<F: FieldOps> {
-    /// a-invariant
+    /// $a_1$-invariant
     pub a1: F,
-    /// a-invariant
+    /// $a_2$-invariant
     pub a2: F,
-    /// a-invariant
+    /// $a_3$-invariant
     pub a3: F,
-    /// a-invariant
+    /// $a_4$-invariant
     pub a4: F,
-    /// a-invariant
+    /// $a_6$-invariant
     pub a6: F,
 }
 
@@ -130,6 +169,7 @@ ref_field_impl! {
         // -------------------------------------------------------------------
 
         /// Returns the five $a$-invariants $[a_1, a_2, a_3, a_4, a_6]$.
+        #[allow(clippy::clone_on_copy)] // want to signal that the a_invariants are copied
         pub fn a_invariants(&self) -> [F; 5] {
             [
                 self.a1.clone(),

ec/tests/curves_legendre_tests.rs

@@ -1,4 +1,4 @@
-use crypto_bigint::{Uint, const_prime_monty_params};
+use crypto_bigint::{const_prime_monty_params, Uint};
 use ec::curve_legendre::LegendreCurve;
 use ec::curve_ops::Curve;
 use ec::point_legendre::LegendrePoint;
@@ -119,6 +119,7 @@ fn legendre_short_weierstrass_coordinate_shift_works() {
     let jc = c.j_invariant();
     let w = c.to_short_weierstrass();
     let jw = w.j_invariant();
+    assert_eq!(jc, jw);
 
     let p = LegendrePoint::new(fp(2), fp(6));
     assert!(c.is_on_curve(&p));

ec/tests/hessian_tests.rs

@@ -1,6 +1,6 @@
 //! Integration tests for generalized Hessian curves.
 
-use crypto_bigint::{Uint, const_prime_monty_params};
+use crypto_bigint::{const_prime_monty_params, Uint};
 
 use ec::curve_hessian::HessianCurve;
 use ec::curve_ops::Curve;
@@ -181,6 +181,8 @@ fn hessian_weierstrass_birational_roundtrip() {
     let wc = curve.to_weierstrass_curve_with_zeta(zeta).unwrap();
     let jw = wc.j_invariant();
 
+    assert_eq!(jc, jw);
+
     let wp = curve
         .map_point_to_weierstrass_with_zeta(&p, zeta)
         .expect("forward birational map");

ec/tests/twisted_hessian_tests.rs

@@ -1,10 +1,9 @@
 //! Integration tests for twisted Hessian curves.
 
-use crypto_bigint::{Uint, const_prime_monty_params};
+use crypto_bigint::{const_prime_monty_params, Uint};
 
 use ec::curve_ops::Curve;
 use ec::curve_twisted_hessian::TwistedHessianCurve;
-use ec::point_ops::{PointAdd, PointOps};
 use ec::point_twisted_hessian::TwistedHessianPoint;
 use fp::field_ops::FieldOps;
 use fp::fp_element::FpElement;

fp/src/_doctest_support.rs

@@ -0,0 +1,34 @@
+//! Hidded modules only used for testing in the documentation
+
+pub mod _doctest_fp_ext {
+    use crate::field_ops::FieldOps;
+    use crate::fp_element::FpElement;
+    use crate::fp_ext::{FpExt, IrreduciblePoly, TonelliShanksConstants};
+    use crypto_bigint::{const_prime_monty_params, Uint};
+
+    const_prime_monty_params!(Fp19Mod, Uint<1>, "0000000000000013", 2);
+    pub type Fp19 = FpElement<Fp19Mod, 1>;
+
+    pub struct QuadPoly;
+    pub struct TSQuad;
+
+    impl IrreduciblePoly<Fp19Mod, 1, 2> for QuadPoly {
+        fn modulus() -> [Fp19; 2] {
+            [Fp19::one(), Fp19::zero()]
+        }
+    }
+
+    impl TonelliShanksConstants<Fp19Mod, 1, 2, 1> for TSQuad {
+        const ORDER: Uint<1> = Uint::<1>::from_u64(360);
+        const HALF_ORDER: Uint<1> = Uint::<1>::from_u64(180);
+        const S: u64 = 3;
+        const T: Uint<1> = Uint::<1>::from_u64(45);
+        const PROJENATOR_EXP: Uint<1> = Uint::<1>::from_u64(22);
+        const TWOSM1: Uint<1> = Uint::<1>::from_u64(4);
+        fn root_of_unity() -> [FpElement<Fp19Mod, 1>; 2] {
+            [Fp19::from_u64(3), Fp19::from_u64(3)]
+        }
+    }
+
+    pub type F19_2 = FpExt<Fp19Mod, 1, 2, 1, QuadPoly, TSQuad>;
+}

fp/src/fp_element.rs

@@ -6,8 +6,8 @@ use std::fmt;
 
 use crate::field_ops::{FieldFromRepr, FieldOps, FieldRandom};
 use crypto_bigint::{
-    NonZero, RandomMod, Uint,
     modular::{ConstMontyForm, ConstPrimeMontyParams},
+    NonZero, RandomMod, Uint,
 };
 use subtle::{Choice, ConditionallySelectable, ConstantTimeEq, CtOption};