From 1bcd44ee9587630f5cd1ff574fb5a58501c50c95 Mon Sep 17 00:00:00 2001
From: Bhargav Annem <bhargav.annem@gmail.com>
Date: Thu, 20 Jun 2024 12:22:37 -0700
Subject: [PATCH] docs: add docs for `fp` and `fp2`

---
 src/fp.rs  | 15 ++++++++++-----
 src/fp2.rs | 16 +++++++++++++++-
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/src/fp.rs b/src/fp.rs
index 3cfcd868..b21c747d 100644
--- a/src/fp.rs
+++ b/src/fp.rs
@@ -11,8 +11,8 @@ use crate::util::{adc, mac, sbb};
 // integers in little-endian order. `Fp` values are always in
 // Montgomery form; i.e., Scalar(a) = aR mod p, with R = 2^384.
 
-#[allow(missing_docs)]
 #[derive(Copy, Clone)]
+/// Represents an element in the finite field Fp.
 pub struct Fp(pub(crate) [u64; 6]);
 
 impl fmt::Debug for Fp {
@@ -158,11 +158,10 @@ impl<'a, 'b> Mul<&'b Fp> for &'a Fp {
 impl_binops_additive!(Fp, Fp);
 impl_binops_multiplicative!(Fp, Fp);
 
-#[allow(missing_docs)]
 impl Fp {
-    /// Builds an element of `Fp` from a little-endian byte representation.
-    pub fn new_unsafe(bytes: [u64; 6]) -> Self {
-        Fp(bytes)
+    /// Builds an element of `Fp` from little-endian limbs.
+    pub fn new_unsafe(limbs: [u64; 6]) -> Self {
+        Fp(limbs)
     }
 
     /// Returns zero, the additive identity.
@@ -177,6 +176,7 @@ impl Fp {
         R
     }
 
+    /// Checks if this element is zero.
     pub fn is_zero(&self) -> Choice {
         self.ct_eq(&Fp::zero())
     }
@@ -328,6 +328,7 @@ impl Fp {
     }
 
     #[inline]
+    /// Computes the square root of this field element.
     pub fn sqrt(&self) -> CtOption<Self> {
         // We use Shank's method, as p = 3 (mod 4). This means
         // we only need to exponentiate by (p+1)/4. This only
@@ -386,6 +387,7 @@ impl Fp {
     }
 
     #[inline]
+    /// Add two field elements together.
     pub const fn add(&self, rhs: &Fp) -> Fp {
         let (d0, carry) = adc(self.0[0], rhs.0[0], 0);
         let (d1, carry) = adc(self.0[1], rhs.0[1], carry);
@@ -400,6 +402,7 @@ impl Fp {
     }
 
     #[inline]
+    /// Returns the negation of this field element.
     pub const fn neg(&self) -> Fp {
         let (d0, borrow) = sbb(MODULUS[0], self.0[0], 0);
         let (d1, borrow) = sbb(MODULUS[1], self.0[1], borrow);
@@ -425,6 +428,7 @@ impl Fp {
     }
 
     #[inline]
+    /// Squares this element.
     pub const fn sub(&self, rhs: &Fp) -> Fp {
         (&rhs.neg()).add(self)
     }
@@ -569,6 +573,7 @@ impl Fp {
     }
 
     #[inline]
+    /// Multiplies two field elements, returning the result in the Montgomery domain.
     pub const fn mul(&self, rhs: &Fp) -> Fp {
         let (t0, carry) = mac(0, self.0[0], rhs.0[0], 0);
         let (t1, carry) = mac(0, self.0[0], rhs.0[1], carry);
diff --git a/src/fp2.rs b/src/fp2.rs
index 0360decb..c7249fbc 100644
--- a/src/fp2.rs
+++ b/src/fp2.rs
@@ -1,5 +1,4 @@
 //! This module implements arithmetic over the quadratic extension field Fp2.
-#![allow(missing_docs)]
 
 use core::fmt;
 use core::ops::{Add, AddAssign, Mul, MulAssign, Neg, Sub, SubAssign};
@@ -9,8 +8,11 @@ use subtle::{Choice, ConditionallySelectable, ConstantTimeEq, CtOption};
 use crate::fp::Fp;
 
 #[derive(Copy, Clone)]
+/// Represents an element in the field Fp2.
 pub struct Fp2 {
+    /// The first component of the Fp2 element.
     pub c0: Fp,
+    /// The second component of the Fp2 element.
     pub c1: Fp,
 }
 
@@ -110,6 +112,7 @@ impl_binops_additive!(Fp2, Fp2);
 impl_binops_multiplicative!(Fp2, Fp2);
 
 impl Fp2 {
+    /// Returns the zero element of Fp2.
     #[inline]
     pub const fn zero() -> Fp2 {
         Fp2 {
@@ -118,6 +121,7 @@ impl Fp2 {
         }
     }
 
+    /// Returns the one element of Fp2.
     #[inline]
     pub const fn one() -> Fp2 {
         Fp2 {
@@ -126,10 +130,12 @@ impl Fp2 {
         }
     }
 
+    /// Checks if this element is zero.
     pub fn is_zero(&self) -> Choice {
         self.c0.is_zero() & self.c1.is_zero()
     }
 
+    /// Generates a random element in Fp2.
     pub(crate) fn random(mut rng: impl RngCore) -> Fp2 {
         Fp2 {
             c0: Fp::random(&mut rng),
@@ -145,6 +151,7 @@ impl Fp2 {
         self.conjugate()
     }
 
+    /// Computes the conjugate of this element.
     #[inline(always)]
     pub fn conjugate(&self) -> Self {
         Fp2 {
@@ -153,6 +160,7 @@ impl Fp2 {
         }
     }
 
+    /// Multiplies this element by the non-residue.
     #[inline(always)]
     pub fn mul_by_nonresidue(&self) -> Fp2 {
         // Multiply a + bu by u + 1, getting
@@ -180,6 +188,7 @@ impl Fp2 {
             | (self.c1.is_zero() & self.c0.lexicographically_largest())
     }
 
+    /// Computes the square of this element.
     pub const fn square(&self) -> Fp2 {
         // Complex squaring:
         //
@@ -203,6 +212,7 @@ impl Fp2 {
         }
     }
 
+    /// Multiplies this element by another element.
     pub fn mul(&self, rhs: &Fp2) -> Fp2 {
         // F_{p^2} x F_{p^2} multiplication implemented with operand scanning (schoolbook)
         // computes the result as:
@@ -222,6 +232,7 @@ impl Fp2 {
         }
     }
 
+    /// Adds another element to this element.
     pub const fn add(&self, rhs: &Fp2) -> Fp2 {
         Fp2 {
             c0: (&self.c0).add(&rhs.c0),
@@ -229,6 +240,7 @@ impl Fp2 {
         }
     }
 
+    /// Subtracts another element from this element.
     pub const fn sub(&self, rhs: &Fp2) -> Fp2 {
         Fp2 {
             c0: (&self.c0).sub(&rhs.c0),
@@ -236,6 +248,7 @@ impl Fp2 {
         }
     }
 
+    /// Negates this element.
     pub const fn neg(&self) -> Fp2 {
         Fp2 {
             c0: (&self.c0).neg(),
@@ -243,6 +256,7 @@ impl Fp2 {
         }
     }
 
+    /// Computes the square root of this element.
     pub fn sqrt(&self) -> CtOption<Self> {
         // Algorithm 9, https://eprint.iacr.org/2012/685.pdf
         // with constant time modifications.